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

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

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
}'

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.

Last updated