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

⚠️
Currently, only one payment method can be specified. Support for multiple payment methods will be added in the future.

Options	displayedPaymentMethods value
You can use the generic card value	`Card`
Or a region-specific card code:	Russia (`RUB`) - `BankCardRU` Kazakhstan (`KZT`) - `BankCardKZ` Uzbekistan (`UZS`) - `BankCardUZ`

Payment Method Features

Freature	Support
Payments	Yes
-- None 3DS	Yes
-- 3DS v1	Yes
-- 3DS v2	Yes
Disbursements	No

Workflow

📗
Auto-Capture: always ON

When our Checkout Form integration is used, capture is initiated automatically immediately after successful authorisation.

As a result, manual capture and cancellation flows are not supported for payments processed through the Checkout Form.

If you need to reverse a completed transaction, please use the standard refund flow via Host-to-Host integration.

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",
  "checkoutForm": true,
  "paymentIntent": {
    "checkoutFormDetails": {
      "template": "string",
      "displayedPaymentMethods": ["Card"],
      "backToStoreRedirectUrl": "string"
    },
    "submittedAmount": {
      "value": 100.05,
      "currency": "USD"
    },
    "description": "Vertex - INTENT 1234",
    "webhookUrl": "webhookUrl"
  },
  "description": "Vertex - INTENT 1234",
  "merchant": {
    "name": "Mustermann",
    "website": "website.io"
  }
}

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order number in the merchant system.
`checkoutForm`	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
`checkoutFormDetails`	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

checkoutFormDetails

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.

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

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.

Each payment attempt creates a new payment object within the intent.

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

This applies to all payment attempts created within the same intent.

For more information about payment webhooks, see the dedicated page

Testing

🚧
Checkout Form testing is not yet supported in the sandbox environment.
At present, sandbox test cases are available for API-based integration flows only. Support for Checkout Form testing in sandbox is planned for a future release.
Please contact your Integration Manager if you need guidance on the currently available testing options.