📘
This payment method is supported in two integration scenarios: Host-to-Host and Hosted Checkout.

For Hosted Checkout, please refer to the dedicated page.

For Host-to-Host integration, please follow the guide below.

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

Payment Method Features

Payment Method	Visa
Country	Kazakhstan
Processing Currencies	KZT
Supported Brands	Visa, Mastercard
Payments	Yes
-- Min per transaction amount	100 KZT
-- Max per transaction amount	500,000 KZT
-- Authentication	3D Secure
Disbursements	No
Refunds	Full & Partial
-- Full Refund	Yes
-- Partial Refund	Yes
-- Multiple Partial Refunds	Yes
Chargebacks	No

Workflow: Payment & Refund

Download in high resolution

Possible Payment Scenarios:

📘
Auto-Capture or Cancellation
To enable automatic capture or cancellation, you must inform our integration team in advance so they can configure the auto-trigger and define the required timer on their side

Name	Steps
Funds Authorisation without 3DS	You send an Intent creation request via the API, including a Payment transaction. Our platform validates the incoming data and checks with the issuing bank whether 3DS verification is required. [3DS verification is not required] Our platform attempts to authorise the funds immediately. Our platform returns the authorisation result (success or failure) in the synchronous response to the Intent creation request.
Funds Authorisation with 3DS	You send an Intent creation request via the API, including a Payment transaction. Our platform validates the incoming data and checks with the issuing bank whether 3DS verification is required. [3DS verification is required] Our platform prepares a redirect URL to handle the 3DS authentication flow (both 3DS v1 and v2) You open the redirect URL in the payer’s browser or in-app web view, initiating the 3DS authentication. The payer completes (or fails) the 3DS authentication with the issuing bank. Our platform processes the 3DS result and attempts to authorise the funds. Our platform notifies you of the final payment status via a webhook (success or failure).

Name

Steps

Funds Authorisation without 3DS

You send an Intent creation request via the API, including a Payment transaction.
Our platform validates the incoming data and checks with the issuing bank whether 3DS verification is required.
[3DS verification is not required] Our platform attempts to authorise the funds immediately.
Our platform returns the authorisation result (success or failure) in the synchronous response to the Intent creation request.

Funds Authorisation with 3DS

You send an Intent creation request via the API, including a Payment transaction.
Our platform validates the incoming data and checks with the issuing bank whether 3DS verification is required.
[3DS verification is required] Our platform prepares a redirect URL to handle the 3DS authentication flow (both 3DS v1 and v2)
You open the redirect URL in the payer’s browser or in-app web view, initiating the 3DS authentication.
The payer completes (or fails) the 3DS authentication with the issuing bank.
Our platform processes the 3DS result and attempts to authorise the funds.
Our platform notifies you of the final payment status via a webhook (success or failure).

List of used API Requests:

Request	Endpoint	Description
Intent Creation	`POST /processing/api/v1/intents`	Creates a new Intent with one or more Payment transactions. The platform validates the request, creates internal payment records, and checks whether 3DS authentication is required.
Manual Payment Capture	`PATCH /processing/api/v1/payments/{paymentId}`	Requests capture of previously authorised funds by setting the payment status to CAPTURED. Used for manual capture flows only.
Manual Payment Cancellation	`PATCH /processing/api/v1/payments/{paymentId}`	Requests cancellation (void) of an authorised payment by setting the payment status to CANCELLED. Used for manual cancellation flows only.
Refund Creation	`POST /api/v1/refunds`	Creates a refund request (full or partial) for a previously captured payment. A separate refund transaction is created and processed independently from the original payment.

Intent Creation Request/Response

📓
Request specifics

Endpoint: POST /processing/api/v1/intents

Purpose: Creates an Intent and a Payment for the selected 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 BankCardKZ

incomingDetails must include: Card Number, Holder Name, Security Code, Expiry Month, and Expiry Year

Intent Request: Example

{
  "clientReferenceId": "1234",
  "payments": [
    {
      "payer": {
        "phone": "+XXXXXXXXXXX"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardKZ",
        "incomingDetails": {
          "number": "4111111111111111",
          "expiryMonth": "12",
          "expiryYear": "2028",
          "cvv": "123",
          "holderName": "JOHN DOE",
          "successUrl": "https://merchant.example.com/payment/success",
          "failureUrl": "https://merchant.example.com/payment/failure",
          "account": "string"
        }
      },
      "submittedAmount": {
        "value": 100.05,
        "currency": "USD"
      },
      "authCurrencyCode": "RUB",
      "description": "Vertex - INTENT 1234",
      "webhookUrl": "webhookUrl"
    }
  ],
  "description": "Vertex - INTENT 1234",
  "merchant": {
    "name": "Mustermann",
    "website": "website.io"
  }
}

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`.
`description`	String	`Optional`	Intent description.
`merchant`	Object	`Optional`	Merchant information to be associated with the request.

payment

Parameter	Type	Required	Description
`payer`	Object	`Conditional`	Payer details. Optional in general, but may be required for specific merchant MCC codes.
`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. It may differ from the submitted currency if FX conversion is applied. 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.

payer

Parameter	Type	Required	Description
`firstname`	String	`Optional`	Payer's first name.
`lastname`	String	`Optional`	Payer's last name.
`phone`	String	`Conditional`	Payer's phone number. Required for merchants with MCC `4814`. Must be provided in international format: `+XXXXXXXXXXX`.
`email`	String	`Optional`	Payer's email address.
`countryIsoCode`	String	`Optional`	Payer's country of residence in ISO 3166-1 alpha-2 format.
`locale`	String	`Optional`	Payer's preferred language locale.
`taxIdentification`	String	`Optional`	Consumer tax identification number.
`merchantPayerReference`	String	`Optional`	Merchant-provided payer reference.

paymentInstrument

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

incomingDetails

Parameter	Type	Required	Description
`number`	String	`Required`	Card number.
`expiryMonth`	String	`Required`	Card expiry month in `MM` format.
`expiryYear`	String	`Required`	Card expiry year in `YYYY` format.
`cvv`	String	`Required`	Card security code (`CVV`/`CVC`).
`holderName`	String	`Optional`	Cardholder name as printed on the card.
`successUrl`	String	`Optional`	URL to which the payer may be redirected after a successful payment flow, if applicable.
`failureUrl`	String	`Optional`	URL to which the payer may be redirected after a failed payment flow, if applicable.
`account`	String	`Conditional`	Additional account-related value. Required for merchants with MCC `6050` or `6051`.

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

Capture / Cancel Payment

🕑
IMPROTANT
The timeframe between the authorization and capture / cancellation must not exceed 5 days

To capture or cancel the payment transaction and release funds on the payer’s account, you must send a Payment Update request.
Use the following endpoint: Update Payment status and specify the action you wish to perform:
- status = CAPTURED - to capture the authorised amount.
- status = CANCELLED - to cancel the authorisation and release the reserved funds
After receiving your request, we will initiate the capture process and send you a standard webhook with the updated transaction status.

Refunds

📘
Refunds cannot exceed the total value of confirmed transactions for the current day.

To initiate the refund (full or partial) to the payer's original payment instrument, you must send a separate Refund request.

Use the following endpoint: Create Refund and specify the following parameters:

{
  "paymentId": 204264682781298700,
  "partial": false,
  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}

{
  "paymentId": 204264682781298700,
  "partial": true,

  // For a partial refund, specify ONLY ONE of the following:
  // - paymentSubmittedAmount (original/submitted currency)
  // - paymentAuthAmount (authorised/settlement currency)
  
  // This is required when FX conversion was involved in the payment
  // (e.g. KZT -> RUB). The refund will be calculated using the SAME
  // exchange rate as the original payment.
  //
  // Choose the object based on the currency in which you want to
  // define the refund amount, and populate only that object.
    
    


// Option 1: Submitted currency (inactive example)
//    "paymentSubmittedAmount": {
//    "value": 100.05,
//    "currency": "KZT"
//  },
    
    
// Option 2: Authorised currency (active example)
	"paymentAuthAmount": {
    "value": 100.05,
    "currency": "RUB"
  },

  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}

Refund amount rules

Rule	Description
Full refund	Send `paymentId` and set `partial` to `false`, or omit `partial` entirely. The full refundable amount will be refunded.
Partial refund	Set `partial` to `true` and provide exactly one of the following objects: `paymentSubmittedAmount` or `paymentAuthAmount`.
Mutually exclusive amount objects	Do not send `paymentSubmittedAmount` and `paymentAuthAmount` in the same request.
FX payments	If the original payment involved FX conversion, the refund is calculated using the same exchange rate as the original payment.
Currency choice	Use `paymentSubmittedAmount` if you want to define the refund in the original submitted currency. Use `paymentAuthAmount` if you want to define the refund in the authorised or settlement currency.

Top-Level Refund Request Parameters

Parameter	Type	Required	Description
`paymentId`	int64	`Required`	Identifier of the original payment transaction to which this refund applies. Use the `paymentId` returned in the original payment or Intent creation response.
`partial`	Boolean	`Optional`	Indicates whether the refund is partial or full. `true` - partial refund. `false` - full refund. If omitted, the platform treats the request as a full refund.
`paymentSubmittedAmount`	Object	`Conditional`	Refund amount in the original submitted currency. Required when `partial = true` and the refund amount is defined in the submitted currency. Do not send together with `paymentAuthAmount`.
`paymentAuthAmount`	Object	`Conditional`	Refund amount in the authorised or settlement currency. Required when `partial = true` and the refund amount is defined in the authorised currency. Do not send together with `paymentSubmittedAmount`.
`reason`	String	`Optional`	Free-form refund reason. Used for informational and audit purposes.
`webhookUrl`	String	`Optional`	URL to which refund status change webhooks will be sent.

paymentSubmittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Refund amount value in the original submitted currency.
`currency`	String	`Required`	Refund currency in ISO 4217 alpha-3 format. Must match the original submitted currency.

paymentAuthAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Refund amount value in the authorised or settlement currency.
`currency`	String	`Required`	Refund currency in ISO 4217 alpha-3 format. Must match the original authorised or settlement currency.

After the creation of the refund request you must wait for the callback, that will provide you with the latest transaction status

Webhooks

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

Test Data

Our system allows emulating different test cases in the sandbox environment. To simulate specific scenarios and receive different results, use the intent.description parameter.

Payment Test flow

Download in high resolution

FRICTIONLESS FLOW (FF) CASES - No 3DS

List of Test Scenarios

No	Case	intent.description	final paymentStatus
FF_1	Successful Authorization & Capture (Manual or automatic capture)	--	CAPTURED
FF_2	Successful Authorization & Cancellation (Manual or automatic cancellation)	--	CANCELLED
FF_3	Declined authorisation	No3dsFailedAuthorization	DECLINED
FF_4	Successful Authorisation & Unsuccessful Capture (Manual or automatic capture)	No3dsFailedCaptureOrCancellation	DECLINED
FF_5	Successful Authorisation & Unsuccessful Cancellation (Manual or automatic cancellation)	No3dsFailedCaptureOrCancellation	AUTHORIZED
FF_6	Expired authorisation	No3dsExpiredAuthorization	CANCELLED

Frictionless Step-by-Step Scenario Description

No	Case	Steps
FF_1	Successful Authorization & Capture (Manual or automatic capture)	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation, with payment status = AUTHORIZED You receive a webhook notifying you that the payment status has changed into AUTHORIZED. You send a capture request for the authorised payment (or just wait if the auto-capture was configured) You receive a successful response You receive a webhook notifying you that the payment status has changed into CAPTURED
FF_2	Successful Authorization & Cancellation (Manual or automatic cancellation)	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation, with payment status = AUTHORIZED You receive a webhook notifying you that the payment status has changed into AUTHORIZED. You send a cancellation request for the authorised payment (or just wait if the auto-cancellation was configured) You receive a successful response You receive a webhook notifying you that the payment status has changed into CANCELLED
FF_3	Declined authorisation	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation Our platform emulates a unsuccessful payment completion by the payer. You receive a webhook notifying you that the payment status has changed into DECLINED.
FF_4	Successful Authorisation & Unsuccessful Capture (Manual or automatic capture)	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation, with payment status = AUTHORIZED You receive a webhook notifying you that the payment status has changed into AUTHORIZED. You send a capture request for the authorised payment (or just wait if the auto-capture was configured) You receive an unsuccessful response You receive a webhook notifying you that the payment status has changed into DECLINED
FF_5	Successful Authorisation & Unsuccessful Cancellation (Manual or automatic capture)	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation, with payment status = AUTHORIZED You receive a webhook notifying you that the payment status has changed into AUTHORIZED. You send a cancellation request for the authorised payment (or just wait if the auto-cancellation was configured) You receive an unsuccessful response Status won't change, not webhooks will be sent
FF_6	Expired authorisation	You send a request to create a new Intent. You receive a successful response confirming the Intent and Payment creation, with payment status = AUTHORIZED You receive a webhook notifying you that the payment status has changed into AUTHORIZED. Our platform emulates a situation that the authorisation time has expired. The system waits for 5 seconds. You receive a webhook notifying you that the payment status has changed into DECLINED.