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

Payment Method Features

Feature	Description
Country	Kazakhstan
Processing Currencies	KZT - Kazakhstani Tenge
Payments	No
Disbursements	Yes
-- Min per transaction amount	1 000 KZT
-- Max per transaction amount	1 200 000 KZT
Refunds	No
Chargebacks	No

Workflow: Disbursement

Download in high resolution

Possible Disbursement Scenarios:

📘
Account Verification (Optional)
Before creating a disbursement, you may verify whether disbursement to a specific card is allowed using a dedicated endpoint. This step is optional and can help reduce declined transactions.

Name	Steps
Standard Disbursement	1. You send an Intent creation request via the API, including a Disbursement transaction. 2. Our platform validates the incoming data and returns a synchronous acceptance response (accepted or rejected). 3. Upon acceptance, our platform initiates the disbursement operation with the issuing bank / processor. 4. Once the disbursement reaches a final status (PAID_OUT or DECLINED), our platform sends a webhook notification with that status.

Name

Steps

Standard Disbursement

1. You send an Intent creation request via the API, including a Disbursement transaction.
2. Our platform validates the incoming data and returns a synchronous acceptance response (accepted or rejected).
3. Upon acceptance, our platform initiates the disbursement operation with the issuing bank / processor.
4. Once the disbursement reaches a final status (PAID_OUT or DECLINED), our platform sends a webhook notification with that status.

Name Steps

Disbursement Possibility Check This step is optional and can be performed before creating an Intent.
1. You send a verification request via the dedicated endpoint, providing the recipient's payment instrument and amount details.
2. Our platform performs an account-level verification with the issuing bank / processor.
3. Our platform returns a synchronous response with the isDisbursementAllowed attribute (true or false).
4. If the result is satisfactory, you proceed with the standard disbursement flow.

Name	Steps
Disbursement Possibility Check	This step is optional and can be performed before creating an Intent. 1. You send a verification request via the dedicated endpoint, providing the recipient's payment instrument and amount details. 2. Our platform performs an account-level verification with the issuing bank / processor. 3. Our platform returns a synchronous response with the `isDisbursementAllowed` attribute (`true` or `false`). 4. If the result is satisfactory, you proceed with the standard disbursement flow.

List of used API Requests:

Request	Endpoint	Description
Disbursement Possibility Check	`POST /processing/api/v1/disbursements/check`	• Verifies whether the recipient's card can receive a disbursement. • Returns `isDisbursementAllowed` (`true` / `false`). • Optional - can be used before creating an Intent.
Intent Creation	`POST /processing/api/v1/intents`	• Creates a new Intent with one or more Disbursement transactions. • The platform validates the request, creates internal disbursement records, and forwards the request to the issuing bank / processor.

(Optional) Disbursement Possibility Check Request/Response

📓
Request specifics

Endpoint: POST /processing/api/v1/disbursements/check

Purpose: Verifies whether a disbursement to the recipient's card is allowed before creating an Intent.

Required headers: Authorization, settlement-account-id

For this method:

payeePaymentInstrument.paymentMethodName must be set to Bank_Card_KZ

payeePaymentInstrument.incomingDetails must include the recipient's card number (16 digits)

Check Request: Example

⚠️
submittedAmount and authAmount together have four fields (value + currency for each), but only three must be provided - the fourth is derived by our backend based on your business case (with or without FX).

The example below covers the most common case: disbursement without currency conversion (KZT → KZT).

For full guidance, see Amount Fields: submittedAmount and authAmount.

{
  "payeePaymentInstrument": {
    "paymentMethodName": "Bank_Card_KZ",
    "incomingDetails": {
      "number": "4111111111111111"
    }
  },
  "submittedAmount": {
    "value": 12300.00,
    "currency": "KZT"
  },
  "authAmount": {
    "currency": "KZT"
  }
}

Check Request: Fields Description

Top-Level Request Parameters

Parameter	Type	Required	Description
`payeePaymentInstrument`	Object	`Required`	Payment method and instrument details of the disbursement recipient.
`submittedAmount`	Object	`Required`	Amount and currency submitted for verification.
`authAmount`	Object	`Required`	Authorisation amount and currency. May differ from the submitted amount if FX conversion is applied. If FX is not required, currency should match `submittedAmount.currency`.
`additionalData`	Object	`Optional`	Additional details of the disbursement check.

payeePaymentInstrument

Parameter	Type	Required	Description
`paymentMethodName`	String	`Required`	Payment method name. For this scenario, use `Bank_Card_KZ`.
`incomingDetails`	Object	`Required`	Payment method-specific data required for verification.

incomingDetails

Parameter	Type	Required	Description
`number`	String	`Required`	The recipient's bank card number. Length: 16 characters.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Conditional`	Submitted amount. Provide when the sender defines the amount to be debited. Min: 1 000 / Max: 1 200 000 KZT. Omit when only `authAmount.value` is provided.
`currency`	String	`Required`	Submitted currency in ISO 4217 alpha-3 format. Must be `KZT`.

authAmount

Parameter	Type	Required	Description
`value`	Number	`Conditional`	Authorisation amount. Provide when the recipient must receive an exact amount. Omit when `submittedAmount.value` is provided.
`currency`	String	`Required`	Authorisation currency in ISO 4217 alpha-3 format. Must be `KZT`.

📘
Three of the four amount fields must be provided - the fourth is derived by our backend.
See Amount Fields: submittedAmount and authAmount for the full breakdown of cases.

📓
Response specifics

The response contains the isDisbursementAllowed flag indicating whether the disbursement is permitted.

If the verification fails, errorCode and errorMessage provide additional details.

Check Response: Example

{
  "isDisbursementAllowed": true,
  "paymentAmount": {
    "value": 12300.00,
    "currency": "KZT"
  },
  "receivedAmountCurrencyCode": "KZT"
}

Check Response: Fields Description

Top-Level Response Parameters

Parameter	Type	Required	Description
`isDisbursementAllowed`	Boolean	`Required`	Indicates whether the disbursement to the provided card is allowed (`true` / `false`).
`paymentAmount`	Object	`Optional`	Calculated payment amount returned by the processor.
`receivedAmountCurrencyCode`	String	`Optional`	Currency code of the received amount.
`errorCode`	String	`Optional`	Error code returned when the disbursement is not allowed. See `CheckPossibilityStatusCodeEnum`.
`errorMessage`	String	`Optional`	Error message describing the reason the disbursement is not allowed.
`additionalData`	Object	`Optional`	Additional response details, if any.

Intent Creation Request/Response

📓
Request specifics

Endpoint: POST /processing/api/v1/intents

Purpose: Creates an Intent and a Disbursement 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 Bank_Card_KZ

incomingDetails must include the recipient's card number (16 digits)

Intent Request: Example

⚠️
submittedAmount and authAmount together have four fields (value + currency for each), but only three must be provided - the fourth is derived by our backend based on your business case (with or without FX).

The example below covers the most common case: disbursement without currency conversion (KZT → KZT).

For full guidance, see Amount Fields: submittedAmount and authAmount.

{
  "clientReferenceId": "202510202",
  "useCheckoutForm": false,
  "disbursements": [
    {
      "payeePaymentInstrument": {
        "paymentMethodName": "Bank_Card_KZ",
        "incomingDetails": {
          "number": "4111111111111111"
        }
      },
      "submittedAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "authAmount": {
        "currency": "KZT"
      },
      "webhookUrl": "https://merchant.example.com/webhooks/disbursements"
    }
  ]
}

Intent Request: Fields Description

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order number in the merchant system.
`useCheckoutForm`	Boolean	`Required`	Indicates whether the Intent uses a hosted checkout form. For Host-to-Host disbursements, set `false`.
`disbursements`	Array of Objects	`Required`	List of disbursement objects to be created within the `Intent`.
`description`	String	`Optional`	Intent description (arbitrary string).

disbursement

Parameter	Type	Required	Description
`payeePaymentInstrument`	Object	`Required`	Payment method and instrument details used to process the disbursement.
`submittedAmount`	Object	`Required`	Amount and currency submitted for the disbursement.
`authAmount`	Object	`Required`	Authorisation amount and currency used for the disbursement. May differ from the submitted amount if FX conversion is applied. If FX conversion is not required, currency should match `submittedAmount.currency`.
`description`	String	`Optional`	Disbursement description (arbitrary string).
`webhookUrl`	String	`Optional`	URL to which disbursement status change webhooks will be sent.

payeePaymentInstrument

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

incomingDetails

Parameter	Type	Required	Description
`number`	String	`Required`	The recipient's bank card number. Length: 16 characters.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Conditional`	Submitted disbursement amount. Provide when the sender defines the amount to be debited. Min: 1 000 / Max: 1 200 000 KZT. Omit when only `authAmount.value` is provided.
`currency`	String	`Required`	Submitted disbursement currency in ISO 4217 alpha-3 format. Must be `KZT`.

authAmount

Parameter	Type	Required	Description
`value`	Number	`Conditional`	Authorisation amount used for the disbursement. Provide when the recipient must receive an exact amount. Omit when `submittedAmount.value` is provided.
`currency`	String	`Required`	Authorisation currency in ISO 4217 alpha-3 format. Must be `KZT`.

📘
Three of the four amount fields must be provided - the fourth is derived by our backend.
See Amount Fields: submittedAmount and authAmount for the full breakdown of cases.

📓
Response specifics

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

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

For this payment method, the synchronous response confirms acceptance of the disbursement request - the final status (PAID_OUT / DECLINED) is delivered via webhook.

Intent Response: Example

{
  "intentId": "24148546870213835",
  "payments": [],
  "disbursements": [
    {
      "id": "241485668832161722",
      "paymentMethodId": "PM199507277233246209",
      "paymentMethodName": "Bank_Card_KZ",
      "submittedAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "authAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "payeePaymentInstrument": {
        "id": "3525967789943272833",
        "paymentMethodId": "PM199507277233246209",
        "paymentMethodName": "Bank_Card_KZ",
        "storedDetails": {
          "number": "411111******1111"
        }
      },
      "createdAt": "2026-05-05T09:44:33Z",
      "processingStatusCode": "CODE_PT0000",
      "status": "ACCEPTED"
    }
  ],
  "paymentCreationErrors": [],
  "disbursementCreationErrors": [],
  "clientReferenceIntentId": "202510202",
  "intentStatus": "CREATED",
  "checkoutForm": false
}

Response Description

Top-Level Response Parameters

Parameter	Type	Required	Description
`intentId`	String	`Required`	Unique identifier of the `Intent` in our platform.
`payments`	Array	`Required`	List of `Payment` objects. Empty for disbursement-only intents.
`disbursements`	Array of Objects	`Required`	List of `Disbursement` objects created within the `Intent`.
`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.
`clientReferenceIntentId`	String	`Required`	Order number in the merchant system. 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.
`processingStatusCode`	String	`Optional`	Processing status code at intent level. Returned when applicable.
`statusMessage`	String	`Optional`	Status message. Returned when an error occurs.
`description`	String	`Optional`	Intent description. Returned from the request.
`checkoutForm`	Boolean	`Optional`	Indicates whether the Intent uses a hosted checkout form.

disbursement

Parameter	Type	Required	Description
`id`	String	`Required`	Unique identifier of the `Disbursement` in our platform.
`paymentMethodId`	String	`Required`	Unique identifier of the payment method in our platform.
`paymentMethodName`	String	`Required`	Payment method name. Returned from the request.
`submittedAmount`	Object	`Required`	Submitted disbursement amount and currency. Returned from the request.
`authAmount`	Object	`Required`	Authorisation amount and currency used for the disbursement.
`payeePaymentInstrument`	Object	`Required`	Payment instrument information associated with the disbursement.
`createdAt`	String	`Required`	Disbursement creation timestamp in ISO 8601 (`date-time`) format.
`processingStatusCode`	String	`Optional`	Processing status code. May indicate success or an error.
`statusMessage`	String	`Optional`	Status message. Returned when an error occurs.
`status`	String	`Required`	Current disbursement status. See the dedicated section of this API guide for possible values and the status model.
`additionalData`	Object	`Optional`	Method-specific data, if applicable.

payeePaymentInstrument

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

storedDetails

Parameter	Type	Required	Description
`number`	String	`Required`	Recipient's card number (masked). Returned from the request.

Webhooks

🔗
This section summarises the webhook events triggered for Bank_Card_KZ disbursements.
For payload structure, examples, retry policy and delivery conditions, see the dedicated pages: Webhooks: Overview and Webhooks: Example.

When Webhooks Are Sent

A webhook is dispatched to your webhookUrl when the disbursement reaches a final status:

Status	Trigger
`PAID_OUT`	The disbursement has been successfully completed and funds have been delivered to the recipient.
`DECLINED`	The disbursement was rejected by the issuing bank / processor (e.g. invalid card, blocked recipient, regulatory restriction).
`ERROR`	A processing error prevented the disbursement from being completed.

Delivery & Retries

📘

Webhooks are delivered as HTTPS POST requests with a JSON payload to the webhookUrl provided in the original disbursement request.

A delivery is considered successful if your endpoint responds with HTTP 2xx.

If the delivery fails (non-2xx, network error, timeout), the platform retries up to 10 times following a fixed schedule (immediate → 1 min → 5 min → 15 min → 1 h → 3 h → 6 h → 12 h → 24 h → 48 h).

After the 10th attempt, delivery stops permanently.

Full details: Webhooks: Overview.

Payload Example

📓
The webhook payload structure is shared across all transaction types and may evolve over time.
For the up-to-date payload example, see the Webhooks: Example page.

Test Data

🧪
Our sandbox environment lets you simulate the full disbursement lifecycle and trigger every possible final status without involving a real issuing bank.
To force a specific outcome, set the intent.description field to one of the trigger values below.

Sandbox Trigger Reference

Scenario	`intent.description`	Final Status
Successful disbursement	(empty / any value not listed below)	`PAID_OUT`
Disbursement declined	`DisbursementDeclined`	`DECLINED`
Processing error	`DisbursementError`	`ERROR` (returned in the synchronous response)

Test Card Numbers

💳
In the sandbox, any well-formed 16-digit card number (passing the Luhn check) is accepted as the payeePaymentInstrument.incomingDetails.number.
The final disbursement status is controlled by intent.description, not by the card number.

End-to-End Test Flow

Download in high resolution

Scenario	Steps
Successful disbursement	1. Create an Intent via `POST /processing/api/v1/intents` without setting `intent.description` (or with any value not listed in the trigger table). 2. Receive a synchronous response with `disbursement.status = ACCEPTED` and `intent.intentStatus = CREATED`. 3. Receive a final webhook with `status = PAID_OUT`.
Disbursement declined	1. Create an Intent via `POST /processing/api/v1/intents` with `intent.description = "DisbursementDeclined"`. 2. Receive a synchronous response with `disbursement.status = ACCEPTED`. 3. Receive a final webhook with `status = DECLINED`.
Processing error	1. Create an Intent via `POST /processing/api/v1/intents` with `intent.description = "DisbursementError"`. 2. Receive a synchronous response with `disbursement.status = ERROR`.

Tips for Testing

💡

Combine with the possibility check - run POST /processing/api/v1/disbursements/check first to validate the integration of both endpoints.

Verify webhook handling - point webhookUrl at a tool like webhook.site or RequestBin during early integration to inspect raw payloads.

Test FX scenarios - use the 3-of-4 amount field rule (see Amount Fields: submittedAmount and authAmount) to validate both "sender-defined" and "recipient-defined" flows.

Webhook delivery diagnostics - if you don't receive an expected webhook, check that your endpoint returns HTTP 2xx (see Webhooks: Overview for retry behaviour).