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

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

Content-Type

application/json

Authorization

Bearer <token>

Body

Name Type Required Description

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.

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

{
    "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
}

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

Code mẫu

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 --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 --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.

PreviousCalling the API Get Token NextCalling the API Test Callback

Last updated 2 days ago