6️Calling the API Generate VietQR Code

This service allows partners to generate a VietQR payment QR code for users to scan and make direct payments. Depending on the type of VietQR code, different parameters are required.

POST

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

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Required	Description
bankCode	String	Yes	The bank code of the account used to generate the VietQR payment code.
bankAccount	String	Yes	The bank account generating the VietQR payment code.
userBankName	String	Yes	The name of the account holder without Vietnamese diacritics.
content	String	Yes	A brief description of the transaction. Maximum 19 characters, in Vietnamese without diacritics, and no special characters.
qrType	Integer	Yes	Depending on the type of QR code to be generated, use the corresponding value: + Static VietQR: 1 + Semi-Dynamic VietQR: 3 + Dynamic VietQR: 0
amount	Long	Optional	The amount to be paid. (Required if qrType = 0 or 3)
orderId	String	Optional	The transaction ID to be managed by the partner. The orderId will be returned when the system receives the transaction event that matches the QR code transaction. (Required if qrType = 0)
transType	String	Optional	Specify whether the transaction is a debit (D) or credit (C). Default is C. (Required if qrType = 0)
terminalCode	String	Optional	The code of the store or point of sale. (Required if qrType = 1 or 3)
serviceCode	String	Optional	The code for the product or service being paid for. (Required if qrType = 3)
subTerminalCode	String	Optional	The code for a sub-store or branch.
sign	String	Optional	A digital signature to verify the transaction.
urlLink	String	Optional	The page the user is redirected to after scanning the QR code and making the payment.
note	String	Optional	Any additional notes or comments for the transaction.
additionalData	Object	Optional	Optional parameters that may be needed for specific scenarios or configurations.

Response

200

{
    "bankCode": "bank_code",                        // Bank code
    "bankName": "bank_name",                        // Name of the bank
    "bankAccount": "bank_account_for_receiving_payment", // Account for receiving payments
    "userBankName": "account_holder_name",          // Account holder's name
    "amount": "payment_amount",                      // Amount to be paid
    "content": "payment_description",                // Payment description
    "qrCode": "QR_code_as_string",                  // QR code as a string
    "imgId": "bank_image_id",                       // Image ID for the bank
    "existing": "1: already_created_on_VietQR_system_successfully", // Status of the QR code creation
    "transactionId": "QR_identifier_id",            // ID for tracking the QR transaction
    "transactionRefId": "QR_reference_id",          // Reference ID for the transaction
    "qrLink": "QR_code_as_link",                    // QR code as a link
    "terminalCode": "point_of_sale_code",           // Code for the point of sale
    "subTerminalCode": "sub_point_of_sale_code",    // Sub-point of sale code
    "serviceCode": "product_service_code",          // Code for the service or product
    "orderId": "order_id",                          // Order ID for tracking
    "additionalData": "extra_information"           // Any additional information
}

400

{
    "status": "FAILED",
    "message": "mã_lỗi_và_mô_tả_lỗi"
}

---

Code mẫu

cURL for Dynamic QR

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "payment_amount",                                     // Amount to be paid
    "content": "payment_description",                               // Description of the payment
    "bankAccount": "receiving_bank_account",                       // Bank account for receiving payment
    "bankCode": "bank_code",                                       // Bank code
    "userBankName": "account_holder_name",                         // Name of the account holder
    "transType": "C:incoming_transaction/D:outgoing_transaction",  // Transaction type (C for incoming, D for outgoing)
    "orderId": "order_id",                                        // Order ID for transaction
    "sign": "signature",                                           // Signature for authentication
    "serviceCode": "product_service_code",                        // Code for the product or service
    "qrType": "qr_type: 0",                                       // Type of QR (0 for dynamic, etc.)
    "terminalCode": "point_of_sale_code",                         // Point of sale code
    "subTerminalCode": "sub_point_of_sale_code",                  // Sub-point of sale code
    "note": "qr_note",                                            // Note associated with the QR code
    "urlLink": "redirect_link_if_successful_payment",            // Link to redirect if QR payment is successful
    "additionalData": "additional_data_for_QR_can_be_empty"      // Additional data that can be sent
}'

cURL Semi-Dynamic QR

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "amount_of_the_product",                              // Amount for the product
    "content": "payment_description",                                // Payment description
    "bankAccount": "receiving_bank_account",                        // Receiving bank account
    "bankCode": "bank_code",                                        // Bank code
    "userBankName": "account_holder_name",                          // Account holder name
    "transType": "C:incoming_transaction/D:outgoing_transaction",   // Transaction type (C for incoming, D for outgoing)
    "qrType": 3,                                                   // Type of QR code (3 for semi-dynamic)
    "terminalCode": "synchronized_point_of_sale_code",             // Point of sale code
    "serviceCode": "product_service_code"                           // Product service code
}'

cURL tạo mã QR tĩnh

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=A2494C77F9BCB561B15CDFDF6FF2CD1F' \
--header 'Content-Type: application/json' \
--data '{
    "content": "payment_description",                              // Description of the payment
    "bankAccount": "receiving_bank_account",                        // Receiving bank account
    "bankCode": "bank_code",                                        // Bank code
    "userBankName": "account_holder_name",                          // Account holder name
    "transType": "C:incoming_transaction/D:outgoing_transaction",   // Transaction type (C for incoming, D for outgoing)
    "qrType": 1,                                                   // Type of QR code (1 for static)
    "terminalCode": "synchronized_point_of_sale_code"             // Point of sale code
}'

---

FAQs

What is the purpose of the Generate VietQR Code API?

The Generate VietQR Code API is used to create QR payment codes for transactions. This QR code can be scanned by customers to make payments directly from their bank accounts.

What information do I need to provide to create a payment QR code?

To create a payment QR code, you need to provide information such as the amount, order code, recipient information, and the bank account details of the recipient. This information will be encoded into the QR code. You can find detailed information required for each type of QR code above.

How can I know if the QR code has been successfully created?

When the QR code is successfully created, the API will return the QR code image as a string along with detailed information related to the transaction. If an error occurs, you will receive an error message in the response.

How do I handle errors when calling the Generate VietQR Code API?

If you encounter an error when calling the API, first check the input information such as the amount, account information, and order code. Ensure that this information is accurate and valid. If the problem persists, please contact VietQR's technical support for assistance.

What applications can scan the QR code?

The QR code created by the VietQR API can be scanned by any banking application that supports QR payment standards in Vietnam, or by e-wallet applications with QR scanning features.

Here’s the translation of your text into English:

No, the VietQR API will automatically encode the necessary information when creating the QR code. You only need to ensure that the information sent to the API is accurate and complete.