Integration GuideAPI Reference
Integration Guide
  1. Payment Methods
  2. Supported Payment Methods (Hosted Checkout)

"Card" Payment Method

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

⚠️

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

OptionsdisplayedPaymentMethods 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

FreatureSupport
PaymentsYes
-- None 3DSYes
-- 3DS v1Yes
-- 3DS v2Yes
DisbursementsNo

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.

TermMeaning
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": ["Card"],
      "backToStoreRedirectUrl": "string"
    },
    "submittedAmount": {
      "value": 100.05,
      "currency": "USD"
    },
    "description": "Vertex - INTENT 1234",
    "webhookUrl": "webhookUrl",
    "payer": {
      "firstname": "Jake",
      "lastname": "Yellow",
      "phone": "+62285128011",
      "email": "[email protected]",
      "countryIsoCode": "PH",
      "locale": "de-DE",
      "taxIdentification": "798154336790",
      "merchantPayerReference": "12345"
    },
    "payee": {
      "firstNameLocal": "Иван",
      "lastNameLocal": "Иванов",
      "firstNameEng": "Ivan",
      "lastNameEng": "Ivanov",
      "dateOfBirth": "1985-02-14",
      "placeOfBirth": "Smolensk",
      "nationality": "RU",
      "occupation": "Software Engineer",
      "idType": "PASSPORT",
      "idNumber": "AA1234567",
      "taxId": "123456789",
      "currentAddress": {
        "country": "RU",
        "city": "Smolensk",
        "addressLine": "Minusinskaya st., 6, 10",
        "postCode": "720001"
      },
      "email": "[email protected]",
      "phone": "+79001234567",
      "companyName": "ABC Ltd.",
      "companyRegistrationNumber": "987654321",
      "companyTaxId": "321654987",
      "companyRegisteredAddress": "Smolensk, Minusinskaya st., 6",
      "merchantPayeeReference": "12345",
      "additionalData": {
        "customField": "customValue"
      }
    }
  },
  "description": "Vertex - INTENT 1234",
  "merchant": {
    "name": "Mustermann",
    "website": "website.io"
  },
  "extensionAttributes": {
    "attributeName1": "attributeValue1",
    "attributeName2": "attributeValue2"
  }
}

Top-Level Request Parameters

ParameterTypeRequiredDescription
clientReferenceIdStringRequiredOrder number in the merchant system.
useCheckoutFormBooleanConditionalOptional in general.
Must be set to true when using the Checkout Form integration.
paymentIntentObjectConditionalOptional in general.
Must be provided when using the Checkout Form integration.
descriptionStringOptionalOrder description.
Displayed if paymentIntent.description is not provided.
merchantObjectOptionalMerchant information.
Required if the store name must be displayed on the checkout form.
extensionAttributesObjectOptionalAdditional key-value attributes forwarded to the payment partner as is.
Send only if agreed with our integration team — see the extensionAttributes section below.


paymentIntent

ParameterTypeRequiredDescription
formDetailsObjectOptionalCheckout parameters
submittedAmountObjectRequiredOrder amount and currency
descriptionStringOptionalOrder Description that can be displayed on the Checkout Form.
webhookUrlStringRequiredURL to which we will send webhooks related to payments created within the Intent and their status changes
payerObjectOptionalPayer (consumer) details. May be used to pre-fill the checkout form and for compliance/risk purposes.
payeeObjectOptionalPayee (recipient/beneficiary) details. Used for compliance and reporting purposes when applicable.


formDetails

ParameterTypeRequiredDescription
templateStringOptionalThe name of the checkout template to be used.
Multiple templates can be configured and selected for different use cases
displayedPaymentMethodsArray of StringsOptionalList 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
backToStoreRedirectUrlStringOptionalURL to which the payer is redirected if they leave the Checkout Form or after payment completion. Must start with "https://".


submittedAmount

ParameterTypeRequiredDescription
valueNumberRequiredSubmitted order amount.
May differ from the authorised amount if FX conversion is applied.
currencyStringRequiredSubmitted order currency.

May differ from the authorised amount if FX conversion is applied.


payer

ParameterTypeRequiredDescription
firstnameStringOptionalPayer's first name.
Example: Jake
lastnameStringOptionalPayer's last name.
Example: Yellow
phoneStringOptionalPayer's phone number, including country code.
Example: +62285128011
emailStringOptionalPayer's email address.
Example: [email protected]
countryIsoCodeStringOptionalPayer's country of residence in ISO 3166-1 alpha-2 format.
Example: PH
localeStringOptionalThe locale describing the preferred language of the consumer. Used to localise the checkout form when supported.
Example: de-DE
taxIdentificationStringOptionalThe consumer tax identification number (e.g., social security identification). Required by some payment methods or jurisdictions.
Example: 798154336790
merchantPayerReferenceStringOptionalThe merchant-provided payer reference. Allows linking the payer to an internal customer record on the merchant side.
Example: 12345


payee

ParameterTypeRequiredDescription
firstNameLocalStringOptionalPayee's first name in the local language.
Example: Иван
lastNameLocalStringOptionalPayee's last name in the local language.
Example: Иванов
firstNameEngStringOptionalPayee's first name in English.
Example: Ivan
lastNameEngStringOptionalPayee's last name in English.
Example: Ivanov
dateOfBirthStringOptionalPayee's date of birth in YYYY-MM-DD format.
Example: 1985-02-14
placeOfBirthStringOptionalPayee's place of birth.
Example: Smolensk
nationalityStringOptionalPayee's nationality in ISO 3166-1 alpha-2 format.
Example: RU
occupationStringOptionalPayee's occupation.
Example: Software Engineer
idTypeStringOptionalType of identification document presented by the payee (e.g., PASSPORT, ID_CARD).
Example: PASSPORT
idNumberStringOptionalIdentification document number that matches the idType.
Example: AA1234567
taxIdStringOptionalPayee's personal tax identification number.
Example: 123456789
currentAddressObjectOptionalPayee's current residential address. See the currentAddress table below for the field structure.
emailStringOptionalPayee's email address.
phoneStringOptionalPayee's phone number.
companyNameStringOptionalName of the company the payee represents (when the payee is a legal entity).
Example: ABC Ltd.
companyRegistrationNumberStringOptionalRegistration number of the payee's company.
Example: 987654321
companyTaxIdStringOptionalTax identification number of the payee's company.
Example: 321654987
companyRegisteredAddressStringOptionalRegistered legal address of the payee's company.
merchantPayeeReferenceStringOptionalThe merchant-provided payee reference. Allows linking the payee to an internal record on the merchant side.
Example: 12345
additionalDataObjectOptionalFree-form key/value object for any additional payee details required by specific payment methods or compliance rules.


payee.currentAddress

ParameterTypeRequiredDescription
countryStringOptionalCountry of the address in ISO 3166-1 alpha-2 format.
Example: RU
cityStringOptionalCity.
Example: Smolensk
addressLineStringOptionalStreet address line.
Example: Minusinskaya st., 6, 10
postCodeStringOptionalPostal / ZIP code.
Example: 720001


merchant

ParameterTypeRequiredDescription
nameStringOptionalThe name of store, that might be displayed on the checkout form if configured
websiteStringOptionalThe website of the store


extensionAttributes

A free-form set of key-value attributes that our platform forwards to the payment partner as is — the content is not validated, transformed, or mapped on our side.

  • The payment partner may require additional payment or payer attributes (for example, for anti-fraud screening) to improve the payment acceptance rate.
  • The exact set of attribute names and values is agreed individually for your account and will be provided by our integration team.
  • Send this object only if its usage has been explicitly agreed for your account. If the object is omitted, payment processing is not affected.
  • The object is not returned in API responses (Intent or Payment details) or in webhooks.
ParameterTypeRequiredDescription
{attributeName}StringOptionalAttribute name and value as advised by our integration team.


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 in Sandbox

The bank card emulator simulates the full Checkout payment lifecycle in the sandbox environment. Use the test cards below to reproduce specific authorisation and capture outcomes.

⚠️

Use the listed test cards only. The card number is entered by the payer on the checkout page, after the Intent has been created. If the payer enters a card that is not on this list, authorisation will fail. Cards from the list are the only ones guaranteed to drive the emulator through a complete flow.

What the Checkout emulator covers

  • Available in the sandbox environment only.
  • Immediate capture is performed automatically after a successful authorisation. Manual capture and cancellation are not applicable to Checkout — any client settings related to capture mode are ignored.
  • The flow (Frictionless or Challenge) and the outcome at each stage are determined by the PAN only. Expiry date, CVV, and cardholder name do not affect emulator logic — any values that pass form validation are accepted.
  • Amount and currency do not affect emulator behaviour.

Frictionless flow

Authorisation completes without a 3DS challenge. The payer enters card details on the checkout page, and the payment is authorised and captured immediately.

Checkout Frictionless flow

Test cards

NamePANAuthorisationCapture
FF_Card_14462603043025620SuccessSuccess
FF_Card_24462603040971339SuccessFailure
FF_Card_34462603042343024FailureNot applicable

Updated 9 days ago

Did this page help you?