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

• Customer Support: Liên Hệ VietQR - VIETQR.COM

• Email support: [e-mail]

• Hotline: [phone]