Payment Method Definition

📓
displayedPaymentMethods
It is a parameter in the Intent creation request that defines which payment method should be displayed to the payer on the checkout form. It is an alternative to paymentMethodName in host-to-host integration
This parameter is provided in: paymentIntent.formDetails.displayedPaymentMethods
For this method you need to provide VietQR value

Payment Method Features

Feature	Value
Country	Vietnam
Processing Currencies	VND
Payments	Yes
Disbursements	Yes
Refunds	No
Chargebacks	No

Workflow

Download in high resolution

Create Intent Request

Specifics

We use one unified Intent creation request for all supported payment methods: POST /processing/api/v1/intents

The overall structure is the same, but some fields change depending on the payment method and the way of integration: Host-to-Host or Hosted Checkout.

For Host-to-Host we will expect you to complete Payment object

For Hosted Checkout we will expect you to complete PaymentIntent object

The required fields depend on the selected method, so this section must be completed carefully.

The key difference is which object you provide in the request and at what stage the actual payment is created

'Intent' vs 'Payment' vs 'PaymentIntent'

Some objects and parameters in this API may appear similar, but they represent different concepts and are used in different integration scenarios. The explanation below clarifies the purpose of each term.

Term	Meaning
Intent	A universal top-level container for transaction-related operations. Depending on the integration scenario, it may contain objects such as `Payment`, `PaymentIntent`, or other transaction types.
Payment	Used in Host-to-Host integrations. You provide the payment method, payment instrument, amount, currency, and other payment details upfront because the payment flow is handled on your side.
PaymentIntent	Used in Hosted Checkout integrations. It contains the order details and checkout configuration, but not the full payment instrument data. The actual `Payment` object is created later, when the payer completes the checkout form. Multiple payment attempts might occur within one `Intent`. But all of them follows the rules and configuration defined in the corresponding `PaymentIntent`.

Request/Response Description

Request Description

{
  "clientReferenceId": "1234",
  "useCheckoutForm": true,
  "paymentIntent": {
    "formDetails": {
      "template": "string",
      "displayedPaymentMethods": ["VietQR"],
      "backToStoreRedirectUrl": "string"
    },
    "submittedAmount": {
      "value": 1000000,
      "currency": "VND"
    },
    "description": "Vertex - INTENT 1234",
    "webhookUrl": "webhookUrl"
  }
}

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order number in the merchant system.
`useCheckoutForm`	Boolean	`Conditional`	Optional in general. Must be set to `true` when using the Checkout Form integration.
`paymentIntent`	Object	`Conditional`	Optional in general. Must be provided when using the Checkout Form integration.
`description`	String	`Optional`	Order description. Displayed if `paymentIntent.description` is not provided.
`merchant`	Object	`Optional`	Merchant information. Required if the store name must be displayed on the checkout form.

paymentIntent

Parameter	Type	Required	Description
`formDetails`	Object	`Optional`	Checkout parameters
`submittedAmount`	Object	`Required`	Order amount and currency
`description`	String	`Optional`	Order Description that can be displayed on the Checkout Form.
`webhookUrl`	String	`Required`	URL to which we will send webhooks related to payments created within the Intent and their status changes

formDetails

Parameter	Type	Required	Description
`template`	String	`Optional`	The name of the checkout template to be used. Multiple templates can be configured and selected for different use cases
`displayedPaymentMethods`	Array of Strings	`Optional`	List of payment methods to be made available to the payer. If only one payment method is provided, no selection screen is shown and the payer is taken directly to that payment method
`backToStoreRedirectUrl`	String	`Optional`	URL to which the payer is redirected if they leave the Checkout Form or after payment completion. Must start with "https://".

submittedAmount

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

merchant

Parameter	Type	Required	Description
`name`	String	`Optional`	The name of store, that might be displayed on the checkout form if configured
`website`	String	`Optional`	The website of the store

Response Description

{
  "intentId": "string",
  "useCheckoutForm": true,
  "paymentIntent": {
    "intentSessionId": "string",
    "backToStoreRedirectUrl": "string",
    "displayedPaymentMethods": ["VietQR"],
    "submittedAmount": {
      "value": 1000000,
      "currency": "VND"
    },
    "description": "Vertex - INTENT 1234",
    "webhookUrl": "webhookUrl",
    "additionalData": {
      "url": "link to our Checkout Form",
      "expirationDateTime": "YYYY-MM-DDTHH:mm:ssZ"
    }
  },
  "clientReferenceIntentId": "string",
  "merchant": {
    "name": "Mustermann",
    "website": "website.io"
  },
  "processingStatusCode": "CODE_PI0000",
  "statusMessage": "string",
  "description": "string",
  "intentStatus": "CREATED"
}

Top-Level Response Parameters

Parameter	Type	Required	Description
`intentId`	String	`Required`	Unique identifier of the Intent in our platform.
`useCheckoutForm`	Boolean	`Required`	H2H: `false` or empty. Checkout: `true`.
`paymentIntent`	Object	`Conditional`	Optional in general. Required when using the Checkout Form integration.
`clientReferenceIntentId`	String	`Required`	Order number in the merchant system. Returned from the request.
`merchant`	Object	`Optional`	Merchant information. Returned from the request.
`processingStatusCode`	String	`Required`	Processing status code. May indicate success or an error.
`statusMessage`	String	`Optional`	Status message. Returned when an error occurs.
`description`	String	`Optional`	Intent description. Returned from the request.
`intentStatus`	String	`Required`	Current Intent status. See the dedicated section of this API guide for possible values and the status model.

paymentIntent

📓
Note: in the response, the paymentIntent object is flattened compared to the request — checkout form fields (backToStoreRedirectUrl, displayedPaymentMethods) are returned directly on paymentIntent, not inside a nested formDetails object. The template field from the request is not echoed back in the response.

Parameter	Type	Required	Description
`intentSessionId`	String	`Optional`	Our internal id of the session associated with the created Payment Intent.
`backToStoreRedirectUrl`	String	`Required`	URL to which the payer is redirected if they leave the Checkout Form or after payment completion (returned from the request).
`displayedPaymentMethods`	Array of Strings	`Optional`	List of payment methods made available to the payer on the Checkout Form (returned from the request).
`submittedAmount`	Object	`Required`	Order amount and currency (returned from the request).
`description`	String	`Optional`	Order Description (returned from the request).
`webhookUrl`	String	`Optional`	Webhook URL to which we will send webhooks related to payments created within the Intent and their status changes (returned from the request).
`additionalData`	Object	`Required`	An object containing important fields related to the checkout (e.g. checkout URL, session expiration).
`payer`	Object	`Optional`	Payer details (returned from the request, enriched with internal `id`).
`payee`	Object	`Optional`	Payee details (returned from the request, enriched with internal `id`).

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 amount if FX conversion is applied.

additionalData

Parameter	Type	Required	Description
`url`	String	`Required`	Checkout form URL to which the payer must be redirected to complete the payment.
`expirationDateTime`	String	`Optional`	Date and time when the Intent session expires, in format `YYYY-MM-DDTHH:mm:ssZ`. Until that time, the payer can access the checkout form and attempt the payment. Multiple payment attempts may be made during the session lifetime. If the session expires without a successful payment, a new Intent must be created.

merchant

Parameter	Type	Required	Description
`name`	String	`Optional`	The name of the store, that might be displayed on the checkout form if configured (from the request)
`website`	String	`Optional`	The website of the store (from the request)

Webhooks

🔗

After the checkout form is created, the payer can make multiple payment attempts during the payment session lifetime.

By default, the session remains active for 20 minutes, although this value can be changed by your integration manager.

The platform sends webhooks to the URL provided in paymentIntent.webhookUrl from the request whenever the status of the payment changes.

For more information about payment webhooks, see the dedicated page