📓

Please use the following paymentMethodName value when creating the Intent and when completing the disbursement object.

"paymentMethodName": "BankCardKZ" or "BANK_CARD_KZ

Payment Method Features

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.

List of used API Requests:

(Optional) Disbursement Possibility Check Request/Response

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

Intent Creation Request/Response

{
  "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"
    }
  ]
}

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:

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

Here's the table code only:

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

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).