INTEGRATED DOCUMENT FOR PAYMENT SERVICE VIETQR

VietQR VN – Connecting Bank Payments and Businesses

INTEGRATED DOCUMENT FOR PAYMENT SERVICE - VIETQR

*****

– July 2024 –

Table of Contents

Table of Contents 2

Update history 4

Appendix: Terminology and abbreviations 4

A. Context 5

1. Introduction 5

a. Introduction to VietQR payment service 5

b. Purpose of the document 6

c. Scope of the document 6

d. Intended users 6

2. Business operations 7

a. Business process flow 7

b. Description of business process flow 8

1. Description table of VietQR Plus payment process flow 8

2. Description table of VietQR Pro payment process flow 8

3. Payment Service Connection Declaration 9

4. Synchronization of agent and store/point of sale information 9

5. Creating VietQR payment codes 10

6. Receiving balance fluctuation notifications 11

7. Transaction reconciliation 11

B. Technical Information 12

1. Security Authentication Regulations 12

2. Connection Procedure Regulations 12

a. Declaring Service Connection Information 12

b. Information Synchronization Step 12

c. VietQR Receives and Processes Information 12

d. VietQR Simulates Successful Payment Transactions 13

e. Acceptance Testing 13

f. Golive Configuration for the Partner 13

C. VIETQR.VN API Suite 13

List of APIs that integrate payment services 13

1. API Get Token 14

2. API Generate VietQR Code 15

3. API Test Callback 17

4. API Sync MID(s) 18

5. API Get MID(s) 19

6. API Sync TID(s) 20

7. API Get TID(s) 21

8. API Check Transaction 22

D. Partner APIs suit 23

List of APIs to Declare 23

1. API Get Token 24

2. API Transaction Sync 25

E. Error Codes 26

F. Bank Codes 27

G. Contact Us 29

Update history

Date

A* M, D

Updated by

Change Description

11/07/2024

A

Trương Hiệp Hưng Phạm Đức Hiếu

Added sections A, B, C, D, E, F, G (VietQR payment code business)

*A - Add M - Modified D - Deleted

Appendix: Terminology and abbreviations

Term

Description

BĐSD

Balance fluctuation.

Transaction sync/Callback

The term refers to the VietQR system sending Balance fluctuation information through the partner's system.

Context

Introduction

Introduction to VietQR payment service

  • The VietQR code payment service is a technical infrastructure service that enables connection, transmission, and electronic data processing to perform payment transactions via VietQR codes between intermediary payment service providers and banks, thereby allowing payment transactions via VietQR codes at payment accepting units using QR code payment applications. (Source: https://napas.com.vn/dich-vu-thanh-toan-bang-ma-qr-182220812174214287.htm)

  • VietQR payment codes operate in 3 forms, including:

  • Static VietQR Code.

  • Semi-dynamic VietQR Code.

  • Dynamic VietQR Code.

  • Below is a table describing the features, functionalities, and uses of VietQR codes:

Static VietQR

Semi dynamic VietQR

Dynamic VietQR

Feature

- Contains fixed information of one payment account

(bank name, account number, and account holder's name).

- Can be reused for multiple transactions..

- Contains payment amount information and transaction details. The seller can mark the product/service code for each item.

- Contains specific transaction details such as payment amount, transaction details, order code, store code, etc.

- Valid for 15 minutes.

- A new dynamic QR code is created for each payment.

Usage Scope

Applicable to all transactions receiving payment via QR code

Applicable to transactions with the same payment amount.

Applicable to one payment transaction.

Application

- Can be shared online, printed, and displayed to receive payments anytime, anywhere.

- Can be shared online.

(Not recommended for printing and displaying due to usage limitations.)

- Can be shared online. (Not recommended for printing and displaying due to usage limitations.)

- Enhances security by avoiding old QR code misuse.

- Improves user payment experience.

Implementation

User scans the QR code, fills in the payment amount and transaction details, then confirms the transaction.

User scans the QR code and confirms the transaction.

User scans the QR code and confirms the transaction.

  • VietQR offers two payment service packages:

VietQR Plus

VietQR Pro

Mô tả

- Standard connection service package with good stability.

- Reconciliation based on the payment amount and transaction details.

- Priority connection service package with high stability. Supports refund service.

- Reconciliation independent of the payment amount and transaction details.

Hiệu suất

- BĐSD return time of 10-15 seconds.

- Immediate BĐSD return time, about 1-3 seconds.

Purpose of the document

  • This document will introduce the business requirements for integrating the VietQR code payment service. It will provide an overview of the integration services between VietQR and the partner to give the reader information about the transaction flow, business operations, and system operations. This helps partners operate and exploit the product effectively, follow the process correctly, and control the system quality.

Scope of the document

  • This document describes the business requirements and integration process for the API Services integration of the VietQR payment service.

Intended users

  • For partners who need to use the service.

  • For small merchants and businesses.

  • Different VietQR codes are suitable for different transaction purposes and features. Partners need to determine their needs to choose the appropriate VietQR code type, such as static, semi-dynamic, or dynamic codes. Customers can then integrate the VietQR code into their system and guide customers on how to perform payment transactions.

VietQR Type

Needs

Static

- Partners need to create a fixed VietQR code at each store.

Semi-dynamic

- Partners aim to categorize transactions by store.

- Partners need to create a fixed VietQR code for each item.

- Partners aim to categorize transactions by item and by store.

Dynamic

- Partners need to create a fixed VietQR code for each order.

- Partners aim to categorize transactions by order and by store.

Business operations

Business process flow

Image 1: Overview of the integrated VietQR payment service business process flow

Image 2: VietQR Plus payment process flow Image 3: VietQR Pro payment process flow

Description of business process flow

Description table of VietQR Plus payment process flow

Step

Actor

System

Description

Pre-condition

Partner

- Declared connection to the VietQR system. - Linked MBBank/BIDV account on the VietQR system.

1

Customer

Partner

Customer requests payment via VietQR code.

2

Partner

VietQR

Partner sends a request to create a payment QR code to the system.

3

VietQR

Partner

VietQR checks and validates information, IF:

+ Invalid/unavailable: VietQR reports an error.

+ Valid: VietQR creates a new payment code and sends information to the partner.

4

Partner

Partner displays the returned information from VietQR, IF: + Invalid/unavailable: Displays an error message.

+ Valid: Displays the VietQR payment code.

5

Customer

VietQR

Customer scans the displayed VietQR code to pay. VietQR system reconciles the transaction based on the payment amount and transaction details.

6

VietQR

Partner

VietQR returns information as follows: + If transaction information does not match: Send notification to the partner.

+ If the transaction information matches: record the transaction status as successful. Send balance fluctuation notification (BĐSD) and information to the partner.

7

Partner

Customer

Partner receives the notification and displays it to the customer.

Description table of VietQR Pro payment process flow

Step

Actor

System

Description

Pre-condition

Partner

- Declared connection to the VietQR system. - Linked MBBank/BIDV account on the VietQR system.

1

Customer

Partner

Customer requests payment via VietQR code.

2

Partner

VietQR

Partner sends a request to create a payment QR code to the system.

3

VietQR

Partner

VietQR checks and validates information:

+ Invalid/unavailable: VietQR reports an error.

+ Valid: VietQR creates a new payment code and sends information to the partner.

4

Partner

Partner displays the returned information from VietQR: + Invalid/unavailable: Displays an error message.

+ Valid: Displays the VietQR payment code.

5

Customer

VietQR

Customer scans the displayed VietQR code to pay. VietQR system reconciles the transaction independent of the payment amount and transaction details.

6

VietQR

Partner

VietQR returns information as follows:

+ If transaction information does not match: Send notification to the partner.

+ If transaction is successful: Send a success notification to the partner.

7

Partner

Customer

Partner receives the notification and displays it to the customer.

Payment Service Connection Declaration

Below are the steps to integrate the VietQR payment service using API Services:

  • Preparation:

  • Personal or Business bank account of MBBank or BIDV.

  • Information to be provided to VietQR includes: unit name, bank account number, identifying phone number, Tax code/Identity card/Business registration certificate corresponding to the bank account registration information.

  • Step 1: Link bank account on the VietQR system

    • Access the VietQR system and follow the instructions to link the bank account.

    • If you do not have an MBBANK or BIDV bank account, VietQR will provide a test bank account to perform the connection step.

    • Note: When officially operating, you need to link the unit's real bank account.

  • Step 2: Implement the required VietQR API

    • Partner needs to implement two mandatory APIs:.

    • API Get Token: Partner provides login information (username, password) so that VietQR can access the partner's system.

    • API Transaction Sync: Partner follows the regulations provided by VietQR.

  • Step 3: Declare connection information on the VietQR system

  • The unit provides connection information (URL, username, password, etc.) on the VietQR system or directly with VietQR technicians.

  • Note: Specific implementation steps will be detailed by VietQR during the integration process.

Synchronization of agent and store/point of sale information

  • For partners who are general agents, synchronizing subordinate agent information is necessary for managing connections and monitoring the performance of the distribution network.

  • For partners who are agents, synchronizing store/point of sale information is necessary to:

  • Use the service to create static VietQR codes for stores/points of sale.

  • Receive balance fluctuation notifications (BĐSD) and manage transactions according to store/point of sale codes.

  • Detailed information on synchronizing agents and stores/points of sale can be found in Section C.

  • If partner does not intend to use static VietQR codes and management on the VietQR system, this step can be skipped..

Creating VietQR payment codes

  • To create a static VietQR code, the partner needs to synchronize their store/point of sale information. The VietQR system processes classification and reconciliation of transactions into the corresponding stores/points of sale.

  • To create semi-dynamic VietQR codes:

  • The partner should provide product/service codes to classify items.

  • When a semi-dynamic VietQR code is created, the VietQR system can classify payment transactions through the VietQR code corresponding to each item of the partner.

  • To create dynamic VietQR codes:

  • The partner should provide order codes and store/point of sale codes (previously synchronized) to classify transactions.

  • When a dynamic VietQR code is created, the VietQR system records a new transaction with the status "Pending Payment." The customer pays the transaction via the VietQR code successfully, and the VietQR system reconciles successfully; the transaction will be updated to "Payment Successful."

  • Notes when paying via VietQR codes in service packages:

Package

Plus Package

Pro Package

Payment Support

Banks & ewallet systems that support VietQR codes.

Banks and e-wallet systems that support VietQR codes.

Payment Steps

The customer is not allowed to modify: - Static code: Payment reconciliation content.

- Dynamic code: Amount + Payment reconciliation content.

- Semi-dynamic code: Amount + Payment reconciliation content.

The customer is not allowed to modify:

- Dynamic code: Payment amount.

- Semi dynamic code: Payment amount.

Regulations

- If the customer pays via VietQR code and intentionally changes the amount + payment reconciliation content, the VietQR system will not correctly record the transaction information.

- If the customer pays a dynamic VietQR code after the expiration time, the system records it as a new transaction and does not update the old transaction status. Additionally, the expired transaction status is updated to "Cancelled."

- If the customer pays a dynamic VietQR code and intentionally changes the payment amount, the transaction will be immediately cancelled.

- If the customer pays a dynamic VietQR code after the expiration time, the transaction will be immediately cancelled.

Receiving balance fluctuation notifications

  • VietQR sends balance fluctuation information to the partner through the API Transaction Sync provided by the partner (refer to Section D).

  • If VietQR successfully reconciles the transaction (the customer pays the correct transaction): The VietQR system will return the transaction information along with the order code and store/point of sale code for the partner to match on their system.

  • If VietQR cannot reconcile the transaction (the customer modifies the payment information): The VietQR system records the transaction and returns the transaction information without the order code and store/point of sale code.

  • The time to return balance fluctuation information depends on the following factors:

  • The service package being used (VietQR Plus or VietQR Pro). Specific response times can be found in section A.

  • Response time from the bank system.

  • Processing time of the partner returning the product to the customer.

Transaction reconciliation

  • When the partner needs to reconcile transaction information that has been performed through the VietQR system, our system will provide an API to support the partner in reconciling transactions using the order code or transaction code and return specific transaction information for that VietQR payment code.

Technical Information

Security Authentication Regulations

  • Use the HTTPS channel to secure login information.

  • VietQR requires securing information using Basic Authentication and Bearer Token for APIs. Specifically:

  • Both VietQR and the partner provide an API Get Token to return the Bearer Token for authenticating main tasks. The API Get Token is secured with Basic Authentication. VietQR and the partner provide username and password information to access each other's systems.

  • The APIs for generating VietQR codes, synchronizing VietQR partner information, and the partner's API Transaction Sync need to be secured and authenticated using the Bearer Token (returned from the API Get Token).

  • The default validity period of the Bearer Token is 300 seconds.

Connection Procedure Regulations

Declaring Service Connection Information

  • VietQR requires the partner to provide:

  • API Get Token.

  • API Transaction Sync.

  • Username - Password for the API Get Token.

  • Bank account to receive balance fluctuation notifications.

Information Synchronization Step

  • After successfully connecting the service, the partner uses the API Get MID(s) to retrieve their agent information.

  • The partner uses the MID (Merchant ID) to synchronize store/point of sale information.

  • Each store/point of sale of the partner is distinguished by the TID (Terminal ID)/Terminal Code.

  • The partner uses the Terminal Code value to call the API to create the VietQR code and mark transactions.

VietQR Receives and Processes Information

  • If the information is invalid: VietQR will request the partner to check and reconfirm the provided information, ensuring accuracy and compliance with VietQR requirements.

  • If the information is valid: VietQR will request the partner to create several VietQR payment codes in the TEST environment to verify and confirm that the transactions are done correctly.

VietQR Simulates Successful Payment Transactions

  • For the TEST environment, VietQR provides an API to simulate successful transaction payments, pushing balance fluctuation information to the partner's system.

Acceptance Testing

  • After VietQR checks the information and the operational flow is stable and risk-free, both the partner and VietQR proceed to the next step to go live (GOLIVE).

Golive Configuration for the Partner

  • VietQR will set up the Real environment (GOLIVE environment) for the partner. Technicians will then provide information for the partner to operate.

  • The parameters include:

  • API URL for the Real environment (GOLIVE environment).

  • Username - Password to call the API Get Token in the Real environment.

  • After configuration is complete, the partner can use the VietQR payment service.

VIETQR.VN API Suite

List of APIs that integrate payment services

Method

EndPoint

Mô tả

Content-Type

POST

https://<vietqr-host>/vqr/api/token_generate

API Get Token

application/json

POST

https://<vietqr-host>/vqr/api/qr/generate-customer

API Generate VietQR Code

application/json

POST

https://<vietqr-host>/vqr/bank/api/test/transaction-callback

API Test Callback

application/json

POST

https://<vietqr-host>/vqr/api/mid/synchronize/v1

API Sync MID(s)

application/json

POST

https://<vietqr-host>/vqr/api/mid/list-mid

API Get MID(s)

application/json

POST

https://<vietqr-host>/vqr/api/tid/synchronize/v1

API Sync TID(s)

application/json

POST

https://<vietqr-host>/vqr/api/tid/list-tid

API Get TID(s)

application/json

POST

https://<vietqr-host>/vqr/api/transactions/check-order

API Check Transaction

application/json

Note: The values of the fields in the “Required” column in the API description tables.

Mandatory: “○” Conditional: “△” Optional: “‐”

API Get Token

  • Purpose: Used to get bearer token to access the VietQR refund API.

  • Input: application/json

Parameter

Value

Authorization

Basic Authentication: Base64[username:password]

Content-Type

application/json

  • Basic Authentication:

  • "username:password" string is encrypted by Base64.

  • “username” and “password” are provided by VietQR.

  • Output:

  • Status Code 2xx:

No

Parameter

Data Type

Required

Length

Description

1

access_token

String

Bearer Token provided by VietQR to access the VietQR payment code API.

2

token_type

String

Token type "Bearer"

3

expires_in

String

Token expiration time. Default is 300 seconds.

  • Status Code 4xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“FAILED”.

2

message

String

Error code. See Section E.

API Generate VietQR Code

  • Purpose:

  • This API allows partners to create a payment QR Code so that users can scan and make payments directly.

  • Depend on the type of code, partner needs to provide different parameters.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API.

Request Body

Common parameters for all three types of VietQR payment codes.

1

bankCode

String

○

Bank code of the account (Section F).

2

bankAccount

String

○

Bank account creates the VietQR payment code

3

content

String

○

19

Payment content. Maximum 19 characters, no special characters, Vietnamese without diacritics

4

qrType

Integer/String

○

Depend on the type of QR code to be created: - Dynamic VietQR: 0. - Static VietQR: 1.

- Semi-dynamic VietQR: 3.

5

terminalCode

String

△

Store/point of sale code. <required if qrType = 1 AND 3>

6

sign

String

△

Signature.

7

userBankName

String

○

Account holder's name. No diacritics.

9

serviceCode

String

△

19

Product/service code being paid for. <required if qrType = 3>

<optional if qrType = 1 AND 2>

If creating a semi-dynamic VietQR code, the partner needs to provide additional parameters:

8

amount

Long/String

○

Amount to be paid.

If creating a dynamic VietQR code, the partner needs to provide additional parameters:

8

amount

Long/String

○

Amount to be paid.

9

transType

String

○

Transaction type: debit/credit (values: D/C). Default is “C”.

10

orderId

String

△

13

Transaction ID for partner to manage. “orderId” will be returned when the system receives balance fluctuations (information matches with the transaction created by the QR code).

  • Output:

  • Status Code 2xx:

No

Parameter

Data Type

Required

Length

Description

1

bankCode

String

Bank code of the account.

2

bankName

String

Bank name of the account.

3

bankAccount

String

Bank account that created the VietQR payment code.

4

userBankName

String

Account holder's name.

5

amount

Long/String

Amount to be paid.

6

content

String

Payment content.

7

qrCode

String

Payment QR code in String format. |

8

qrLink

String

URL of the payment QR code. Customers can use this link to make payments.

9

terminalCode

String

Store/point of sale code.

  • Status Code 4xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“FAILED”.

2

message

String

Error code. See Section E.

API Test Callback

  • Purpose: This API is designed to test the callback connection from the VietQR system to the partner's system. This is part of the testing and simulation process.

  • Assumption: In this test environment, the API assumes that a transaction has been completed and paid.

  • Note: This API can only be applied in the TEST (UAT) environment.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API.

Request Body

1

bankAccount

String

○

Bank account that created the VietQR payment code.

2

content

String

○

19

Payment content. Maximum 19 characters, no special characters, Vietnamese without diacritics

3

amount

Long/String

○

Amount to be paid.

4

transType

String

○

Transaction type: debit/credit (values: D/C). Default is “C”.

  • Output:

  • Status Code 2xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“SUCCESS”

2

message

String

Returns the transactionId value.

  • Status Code 4xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“FAILED”

2

message

String

Error description from the partner’s API.

Error code. See Section E.

API Sync MID(s)

  • Purpose: This API is used to synchronize information of agents under the main agent.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API

Request Body

1

merchants

List Object

○

2

[merchants][merchantId]

String

○

Agent code. (null if create new)

3

[merchants][merchantFullName]

String

○

Full name of the agent.

4

[merchants][merchantName]

String

○

10

Short name of the agent. No diacritics, no spaces, no special characters.

5

[merchants][merchantAddress]

String

○

Business registration address.

6

[merchants][merchantIdentity]

String

○

Tax code/Identity card/Business registration certificate.

7

[merchants][contactEmail]

String

△

Contact email of the agent.

8

[merchants][contactPhone]

String

△

Contact phone number of the agent.

9

[merchants][career]

String

△

Registered business sector.

10

[merchants][checkSum]

String

○

Encrypted MD5 string of combination:

(password of partner + merchantName + merchantIdentity)

  • Output:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“SUCCESS” or ”FAILED”

Status Code 2xx: “SUCCESS”

2

data

List Object

Information of successfully synchronized agents

3

[data][mid]

String

Agent code.

4

[data][merchantName]

String

Short name of the agent.

Status Code 4xx: “FAILED”

2

message

String

Error code. See Section E.

API Get MID(s)

  • Purpose: This API is used to retrieve the list of synchronized agents under the main agent.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API.

Request Body

1

page

String/Integer

○

Page number to be displayed

2

size

String/Integer

○

Max number of items to be displayed per page

  • Output:

No

Parameter

Data Type

Require

Length

Description

Status Code 2xx: “SUCCESS”

1

metadata

Object

2

[metadata][page]

Integer

Current page

3

[metadata][size]

Integer

Max number of items to be displayed per page

4

[metadata][totalPage]

Integer

Total page

5

[metadata][totalElement]

Integer

Total element

6

data

List Object

Information of successfully synchronized agent.

7

[data][mid]

String

Agent code.

8

[data][merchantFullName]

String

Full name of the agent..

9

[data][merchantName]

String

Short name of the agent

10

[data][address]

String

Business registration address.

11

[data][merchantIdentity]

String

Tax code/Identity card/Business registration

12

[data][contactEmail]

String

Contact email of the agent.

13

[data][contactPhone]

String

Contact phone number of the agent.

Status Code 4xx: “FAILED”

1

status

String

”FAILED”

2

message

String

Error code. See Section E.

API Sync TID(s)

  • Purpose: This API is used to synchronize information of stores/points of sale.

  • Input: application/json

No

Parameter

Data Type

Require

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API.

Request Body

1

terminals

List Object

○

2

[terminals][merchantId]

String

○

Agent code.

3

[terminals][merchantName]

String

○

Short name of the agent. If “merchantId” is provided, “merchantName” is not required.

4

[terminals][terminalCode]

String

○

Store/point of sale code.

5

[terminals][terminalName]

String

○

Store/point of sale name.

6

[terminals][terminalAddress]

String

○

Store/point of sale address.

7

[terminals][bankCode]

String

○

Bank code.

8

[terminals][bankAccount]

String

○

Bank account number.

9

[terminals][checkSum]

String

○

Encrypted MD5 string of combination:

(partners password+bankCode+bankAccount)

  • Output:

No

Parameter

Data Type

Require

Length

Description

1

status

String

“SUCCESS” or ”FAILED”

Status Code xx: “SUCCESS”

2

data

List Object

Information of successfully synchronized stores/points of sale.

3

[data][tid]

String

Store/point of sale ID.

4

[data][terminalCode]

String

Store/point of sale code

5

[data][terminalName]

String

Store/point of sale name

6

[data][bankCode]

String

Bank code

7

[data][bankAccount]

String

Bank account number

Trường hợp trả về Status Code 4xx: “FAILED”

2

message

String

Error code. See Section E.

API Get TID(s)

  • Purpose: This API is used to retrieve the list of synchronized stores/points of sale.

  • Input: application/json

No

Parameter

Data Type

Require

Length

Description

Request Header

1

Authorization

String

○

Bearer Token obtained from the Get Token API.

Request Body

1

page

String/Integer

○

Page number to be displayed

2

size

String/Integer

○

Max number of items to be displayed per page

3

mid

String

○

Agent code.

  • Output:

No

Parameter

Data Type

Require

Length

Description

Status Code 2xx: “SUCCESS”

1

metadata

Object

2

[metadata][page]

Integer

Current page

3

[metadata][size]

Integer

Max number of items to be displayed per page

4

[metadata][totalPage]

Integer

Total page

5

[metadata][totalElement]

Integer

Total element

6

data

List Object

Information of successfully synchronized stores/points of sale.

7

[data][terminalId]

String

Store/point of sale ID

8

[data][terminalCode]

String

Store/point of sale code.

9

[data][terminalName]

String

Store/point of sale name.

10

[data][terminalAddress]

String

Store/point of sale address

11

[data][bankCode]

String

Bank code

12

[data][bankAccount]

String

Bank account number

Status Code 4xx: “FAILED”

1

status

String

“FAILED”

2

message

String

Error code. See Section E.

API Check Transaction

  • Purpose: This API is used to track transactions of Partner’s bank account.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token get from API Get Token.

Request Body

1

bankAccount

String

○

Transaction bank account

2

type

String

○

0: check by orderId; 1: by referenceNumber

3

value

String

○

Value check (orderId or referenceNumber)

4

checkSum

String

○

Encrypted String MD5 of combination: (bankAccount + partner’s username)

  • Output:

  • In case of returning Status Code 4xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“FAILED”

2

message

String

Error code. See Section E.

  • In case of returning Status Code 2xx:

No

Parameter

Data Type

Required

Length

Description

1

status

String

“SUCCESS” or”FAILED”

2

data

List Object

JSON object.

3

[data][orderId]

String

Order ID

4

[data][referenceNumber]

String

referenceNumber need to track.

5

[data][amount]

Long/String

amount.

6

[data][transType]

String

Value: “D” or ”C”

8

[data][timeCreated]

Long

Create time.

9

[data][timePaid]

Long

Paid time.

10

[data][content]

String/Integer

Payment note.

11

[data][type]

Integer

Verify type of this transaction.

0: transaction is created by VietQR system

2: transaction from outside VietQR system

6: refund transaction.

12

[data][refundCount]

Int

Refund count based on payment transaction. <if transType = D => not have this field>

13

[data][amountRefunded]

Long

Refunded amount based on payment transaction <if transType = D => not have this field>

Partner APIs suit

List of APIs to Declare

Method

EndPoint

Mô tả

Content-Type

POST

https://<client-host>/<basepath>/api/token_generate

API Get Token

application/json

POST

https://<client-host>/<basepath>/bank/api/transaction-sync

API Transaction Sync

application/json

Note: The values of the fields in the “Required” column in the API description tables.

Mandatory: “○” Conditional: “△” Optional: “‐”

API Get Token

  1. Purpose: Used to get bearer token to access the VietQR refund API.

  2. Input: application/json

Parameter

Value

Authorization

Basic Authentication: Base64[username:password]

Content-Type

application/json

  • Basic Authentication:

  • "username:password" string is encrypted by Base64.

  • “username” and “password” are provided by Partner.

  • Output:

  • Status Code 2xx:

No

Parameter

Data Type

Required

Length

Description

1

access_token

String

Bearer Token provided by Partner to access the Partner’s push transaction callback API.

2

token_type

String

Token type "Bearer"

3

expires_in

String

Token expiration time. Default is 300 seconds.

API Transaction Sync

  • Purpose: Dùng để lấy bearer token truy cập API Transaction Sync của đối tác.

  • Input: application/json

No

Parameter

Data Type

Required

Length

Description

Request Header

1

Authorization

String

○

Bearer Token get from API Get Token.

Request Body

1

bankaccount

String

○

Bank account that created the VietQR payment code.

2

amount

String

○

Amount to be paid.

3

transType

String

○

Transaction type: debit/credit (values: D/C). Default is “C”.

4

content

String

○

Payment content. Maximum 19 characters, no special characters, Vietnamese without diacritics

  • Output:

No

Parameter

Data Type

Required

Length

Description

1

error

boolean

Partner’s error flag (true/false).

2

errorReason

String

Error code

3

toastMessage

String

Error description

4

data

List Object

Data response.

5

[data][refTransactionId]

String

Reference number of the transaction.

Error Codes

No

Code

Description

1

E02

Invalid amount.

2

E03

Invalid transaction type. “transType”

3

E09

Invalid content.

4

E10

Invalid account number.

5

E05

Unknown error.

6

E24

No bank found for the given bankCode.

7

E39

Invalid checkSum.

8

E42

The partner's account does not have refund permission.

9

E43

Refund failed.

10

E44

Transaction ID (referenceNumber) does not exist.

11

E45

Invalid refund amount (exceeds total amount)

12

E46

Invalid Request Body/Parameter.

13

E51

Invalid bankCode.

14

E58

Incorrect type. Default type = 0.

15

E67

User information not found.

16

E74

Invalid token.

17

E75

Test callback API service is not available.

18

E76

Partner is not registered in the system.

19

E77

Bank account does not match with the information of the partner.

20

E95

Invalid transaction type (field "type" in request body).

21

E96

Corresponding transaction not found.

22

E104

Agent registration information for the partner not found

23

E158

A request waiting to be processed

Bank Codes

No

Bank Code

Bank Name

1

ABB

Ngân hàng TMCP An Bình

2

ACB

Ngân hàng TMCP Á Châu

3

BAB

Ngân hàng TMCP Bắc Á

4

BIDV

Ngân hàng TMCP Đầu tư và Phát triển Việt Nam

5

BVB

Ngân hàng TMCP Bảo Việt

6

CAKE

TMCP Việt Nam Thịnh Vượng - Ngân hàng số CAKE by VPBank

7

CBB

Ngân hàng Thương mại TNHH MTV Xây dựng Việt Nam

8

CIMB

Ngân hàng TNHH MTV CIMB Việt Nam

9

COOPBANK

Ngân hàng Hợp tác xã Việt Nam

10

DBS

DBS Bank Ltd - Chi nhánh Thành phố Hồ Chí Minh

11

DOB

Ngân hàng TMCP Đông Á

12

EIB

Ngân hàng TMCP Xuất Nhập khẩu Việt Nam

13

GPB

Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu

14

HDB

Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh

15

HLBVN

Ngân hàng TNHH MTV Hong Leong Việt Nam

16

HSBC

Ngân hàng TNHH MTV HSBC (Việt Nam)

17

IBK - HCM

Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh TP. Hồ Chí Minh

18

IBK - HN

Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh Hà Nội

19

ICB

Ngân hàng TMCP Công thương Việt Nam

20

IVB

Ngân hàng TNHH Indovina

21

KBank

Ngân hàng Đại chúng TNHH Kasikornbank

22

KBHCM

Ngân hàng Kookmin - Chi nhánh Thành phố Hồ Chí Minh

23

KBHN

Ngân hàng Kookmin - Chi nhánh Hà Nội

24

KLB

Ngân hàng TMCP Kiên Long

25

LPB

Ngân hàng TMCP Bưu Điện Liên Việt

26

MB

Ngân hàng TMCP Quân đội

27

MSB

Ngân hàng TMCP Hàng Hải

28

NAB

Ngân hàng TMCP Nam Á

29

NCB

Ngân hàng TMCP Quốc Dân

30

NHB HN

Ngân hàng Nonghyup - Chi nhánh Hà Nội

31

OCB

Ngân hàng TMCP Phương Đông

32

Oceanbank

Ngân hàng Thương mại TNHH MTV Đại Dương

33

PBVN

Ngân hàng TNHH MTV Public Việt Nam

34

PGB

Ngân hàng TMCP Xăng dầu Petrolimex

35

PVCB

Ngân hàng TMCP Đại Chúng Việt Nam

36

SCB

Ngân hàng TMCP Sài Gòn

37

SCVN

Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam

38

SEAB

Ngân hàng TMCP Đông Nam Á

39

SGICB

Ngân hàng TMCP Sài Gòn Công Thương

40

SHB

Ngân hàng TMCP Sài Gòn - Hà Nội

41

SHBVN

Ngân hàng TNHH MTV Shinhan Việt Nam

42

STB

Ngân hàng TMCP Sài Gòn Thương Tín

43

TCB

Ngân hàng TMCP Kỹ thương Việt Nam

44

TIMO

Ngân hàng số Timo by Ban Viet Bank (Timo by Ban Viet Bank)

45

TPB

Ngân hàng TMCP Tiên Phong

46

Ubank

TMCP Việt Nam Thịnh Vượng - Ngân hàng số Ubank by VPBank

47

UOB

Ngân hàng United Overseas - Chi nhánh TP. Hồ Chí Minh

48

VAB

Ngân hàng TMCP Việt Á

49

VBA

Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam

50

VCB

Ngân hàng TMCP Ngoại Thương Việt Nam

51

VCCB

Ngân hàng TMCP Bản Việt

52

VIB

Ngân hàng TMCP Quốc tế Việt Nam

53

VIETBANK

Ngân hàng TMCP Việt Nam Thương Tín

54

VNPTMONEY

Trung tâm dịch vụ tài chính số VNPT- Chi nhánh Tổng công ty truyền thông (VNPT Fintech)

55

VPB

Ngân hàng TMCP Việt Nam Thịnh Vượng

56

VRB

Ngân hàng Liên doanh Việt - Nga

57

VTLMONEY

Tổng Công ty Dịch vụ số Viettel - Chi nhánh tập đoàn công nghiệp viễn thông Quân Đội

58

WVN

Ngân hàng TNHH MTV Woori Việt Nam

Contact Us

PreviousTạo môi trường test CallbackNextAPI VIETQR - Host2Client