📓
Please use the following paymentMethodName value when creating the Intent and when completing the payment object.
"paymentMethodName": "VietQR"

📘
VietQR is a QR-based push payment method for Vietnam. You create an Intent, receive a QR (and a payment URL) in the synchronous response, and display it to the payer. The payer completes the payment in their banking app, and we notify you of the final status via a webhook.

Payment Method Features

Payment Method	VietQR
Country	Vietnam
Processing Currencies	VND
Payments	Yes
*-- Min per transaction amount*	Vary, depends on your contract
*-- Max per transaction amount*	Vary, depends on your contract
Disbursements	Yes
Refunds	No
Chargebacks	No

Workflow: Payment

Download in high resolution

Possible Payment Scenarios

📘
VietQR has a single integration flow: you generate a QR at Intent creation, then wait for the final status via webhook. The QR resolves to one of two terminal outcomes — Successful Payment (CAPTURED) or Expired QR (DECLINED).

Name	Steps
QR Generation	[1.1] The payer initiates a payment on your side. [1.2] You send an Intent creation request via the API (`POST /processing/api/v1/intents`), including a Payment transaction for VietQR. [1.3] Our platform validates the incoming data, creates the `Intent`, and creates a separate `Payment`. [1.4] Our platform requests a QR from the processor. [1.5–1.6] The processor returns the created QR; our platform returns it to you in the synchronous response to the Intent creation request (`payments[].additionalData.details.qrBase64` and `url`). [1.7] You render the QR (or redirect the payer to `url`) so the payer can complete the payment.
Successful Payment	[2.1] The payer scans the QR and completes the payment. [2.2] The processor returns the payment result to our platform. [2.3: SC] Our platform changes the payment status to `CAPTURED`. [2.4: SC] Our platform sends a webhook with the latest status update.
Expired QR	[2.1] The payer does not complete the payment before the QR expires. [2.3: EQ] Our platform changes the payment status to `DECLINED` (expiration). [2.4: EQ] Our platform sends a webhook with the latest status update.

⚠️
Failed payment attempts
The processor does not register unsuccessful payment attempts.
You will receive only a success (CAPTURED) or an expiration (DECLINED) notification.

List of used API Requests

Request	Endpoint	Description
Intent Creation	`POST /processing/api/v1/intents`	• Creates a new `Intent` with a VietQR `Payment` transaction. • The platform validates the request, creates the internal payment record, requests a QR from the processor, and returns the QR in the synchronous response.

🔗
The final transaction status (CAPTURED or DECLINED) is always delivered asynchronously via a webhook. More on the dedicated page.

Intent Creation Request/Response

📓
Request specifics

Endpoint: POST /processing/api/v1/intents

Purpose: Creates an Intent and a Payment for the VietQR payment method.

Structure: A unified request structure is used for all supported payment methods, but some fields are method-specific.

For this method:

paymentMethodName must be set to VietQR

authCurrencyCode must be set to VND

Intent Request: Example

{
  "clientReferenceId": "1234",
  "payments": [
    {
      "paymentInstrument": {
        "paymentMethodName": "VietQR",
        "incomingDetails": {
          "sessionTimeoutMin": 20
        }
      },
      "submittedAmount": {
        "value": 500000,
        "currency": "VND"
      },
      "authCurrencyCode": "VND",
      "description": "Purchase description",
      "webhookUrl": "https://merchant.example.com/webhooks/payments"
    }
  ]
}

Intent Request: Fields Description

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order number in the merchant system.
`payments`	Array of Objects	`Required`	List of payment objects to be created within the `Intent`.

payment

Parameter	Type	Required	Description
`paymentInstrument`	Object	`Required`	Payment method and payment instrument details used to process the payment.
`submittedAmount`	Object	`Required`	Amount and currency submitted for the payment.
`authCurrencyCode`	String	`Required`	Authorisation currency code to be used for the payment. Always `VND` for this method. If FX conversion is not required, it should match `submittedAmount.currency`.
`description`	String	`Optional`	Payment description.
`webhookUrl`	String	`Required`	URL to which payment status change webhooks will be sent.

paymentInstrument

Parameter	Type	Required	Description
`paymentMethodName`	String	`Required`	Payment method name. For this scenario, use `VietQR`.
`incomingDetails`	Object	`Required`	Payment method-specific data required to initiate the payment.

incomingDetails

Parameter	Type	Required	Description
`sessionTimeoutMin`	Integer	`Optional`	QR / order lifetime in minutes. If not provided, the default of 20 minutes is applied. Min: `1` minute. Max: not limited. A value of `0` is not allowed.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Submitted order amount. VND is a zero-decimal currency, so amounts are typically whole numbers (e.g. `500000`). May differ from the authorised amount if FX conversion is applied.
`currency`	String	`Required`	Submitted order currency in ISO 4217 alpha-3 format. May differ from the authorised currency if FX conversion is applied.

📓
Response specifics

The Intent creation response is generally consistent across all supported payment methods.

Common fields describe the Intent, the Payment, and the current transaction status.

Method-specific data is returned in payments[].additionalData.details:

qrBase64 — the VietQR code encoded in Base64 (PNG). Render it and display it to the payer.

Receiving virtual-account details (bankBin, bankCode, bankName, bankBranch, accountNo, accountName) — can be shown as a manual bank-transfer fallback.

Intent Response: Example

{
  "intentId": "232510340021612544",
  "payments": [
    {
      "id": "232510340646563840",
      "submittedAmount": {
        "value": 500000,
        "currency": "VND"
      },
      "authAmount": {
        "value": 500000,
        "currency": "VND"
      },
      "paymentInstrument": {
        "id": "PI204264628196626432",
        "paymentMethodId": "PM199507277233246209",
        "paymentMethodName": "VietQR",
        "storedDetails": {
          "sessionTimeoutMin": 20
        }
      },
      "status": "ACCEPTED",
      "additionalData": {
        "details": {
          "qrBase64": "iVBORw0KGgoAAAANSUhEUgAA... (Base64-encoded QR image)",
          "bankBin": "970418",
          "bankCode": "BIDV",
          "bankName": "BIDV",
          "bankBranch": "",
          "accountNo": "970418225675",
          "accountName": "NGUYEN VAN A"
        }
      }
    }
  ],
  "disbursements": [],
  "clientReferenceIntentId": "1234",
  "paymentCreationErrors": [],
  "disbursementCreationErrors": [],
  "intentStatus": "IN_PROGRESS"
}

Response Description

Top-Level Response Parameters

Parameter	Type	Required	Description
`intentId`	String	`Required`	Unique identifier of the `Intent` in our platform.
`payments`	Array of Objects	`Required`	List of `Payment` objects created within the `Intent`.
`disbursements`	Array	`Optional`	List of disbursement objects created within the `Intent`. Empty if no disbursements were created.
`clientReferenceIntentId`	String	`Required`	Order number in the merchant system. Returned from the request.
`paymentCreationErrors`	Array	`Required`	List of payment creation errors, if any. Empty if no errors occurred.
`disbursementCreationErrors`	Array	`Required`	List of disbursement creation errors, if any. Empty if no errors occurred.
`intentStatus`	String	`Required`	Current `Intent` status. See the dedicated section of this API guide for possible values and the status model.

payment

Parameter	Type	Required	Description
`id`	String	`Required`	Unique identifier of the `Payment` in our platform.
`submittedAmount`	Object	`Required`	Submitted payment amount and currency. Returned from the request.
`authAmount`	Object	`Required`	Authorised amount and currency used for the payment.
`paymentInstrument`	Object	`Required`	Payment method information associated with the payment.
`status`	String	`Required`	Current payment status. See the dedicated section of this API guide for possible values and the status model.
`additionalData`	Object	`Optional`	Method-specific data required to continue or complete the payment flow.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Submitted order amount. Returned from the request. May differ from the authorised amount if FX conversion is applied.
`currency`	String	`Required`	Submitted order currency. Returned from the request. May differ from the authorised currency if FX conversion is applied.

authAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Authorised amount used for the payment. May differ from the submitted amount if FX conversion is applied.
`currency`	String	`Required`	Authorisation currency used for the payment. Always `VND` for this method.

paymentInstrument

Parameter	Type	Required	Description
`id`	String	`Optional`	Unique identifier of the payment instrument in our platform.
`paymentMethodId`	String	`Optional`	Unique identifier of the payment method in our platform.
`paymentMethodName`	String	`Optional`	Payment method name. Returned from the request.
`storedDetails`	Object	`Optional`	Stored payment instrument details. Returned when applicable.

storedDetails

Parameter	Type	Required	Description
`sessionTimeoutMin`	Integer	`Optional`	QR / order lifetime in minutes. Returned from the request.

additionalData

Parameter	Type	Required	Description
`details`	Object	`Required`	Method-specific details required to continue or complete the payment flow.

details

Parameter	Type	Required	Description
`qrBase64`	String	`Required`	VietQR code encoded in Base64 (PNG). Render it and display it to the payer.
`bankBin`	String	`Optional`	NAPAS bank identification number (BIN) of the receiving bank.
`bankCode`	String	`Optional`	Receiving bank code.
`bankName`	String	`Optional`	Receiving bank name.
`bankBranch`	String	`Optional`	Receiving bank branch, when provided.
`accountNo`	String	`Optional`	Virtual account number the payer transfers the funds to.
`accountName`	String	`Optional`	Account holder name.

Webhooks

🔗
More about Payment Webhooks on the dedicated page.
You will receive a webhook on each status change of any transaction you created.

After the transaction is processed and reaches its final status (CAPTURED or DECLINED), the platform notifies you of the latest status change via the webhook.
In some cases the acquirer may return extra information about the transaction. In that case we include additional data in the webhook.

Refunds

📘
Refunds are not applicable
This payment method does not have a native refund option.
However, there is a way to return money to a customer — using the disbursement functionality.

Testing in Sandbox

🚧
Emulator for this method is temporarily not available