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
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 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
Customer Support: Liên Hệ VietQR - VIETQR.COM
Email support: sales@vietqr.vn
Hotline: 1900 6234