Configure xpayment webhooks, handle six payment and refund events, verify payloads, retry failures, and process deliveries idempotently.
A webhook is an HTTP POST that xpayment sends to your server when a payment or refund reaches a relevant status. Your handler can then confirm an order, release a reservation, or record a refund without repeatedly calling the API.
The flow is the same for phone invoices, payment links, and payments from the dashboard:
Your server -> xpayment -> Kaspi
|
status changes
v
Your server <- webhook <- xpayment
Webhook subscriptions are shared across the organization: events arrive for payments created through API v2, API v1, and the dashboard, so you do not need a separate subscription for each way.
xpayment checks pending payments and QR tokens with background processes every 5 seconds, and the webhook queue is scanned every 2 seconds. These are launch intervals, not a guaranteed delivery time: Kaspi’s response, load, and the network also affect it.
Use webhooks as the main notification channel. GET /v2/payments/{payment_id} is useful for reconciliation and for recovery after your handler was unavailable.
A webhook has no amount and no status. It only says that an event happened to that payment. After receiving it, fetch the payment with
GET /v2/payments/{payment_id}and rely on its status.
You need an xpayment account and a public address for your handler. Use only HTTPS in production. The API currently checks only that the address is non-empty, so you must supply a valid, reachable HTTPS address.
Production webhook) by hand.The subscription is active as soon as it is created. Keep the secret in a secret manager: lists and updates of subscriptions do not return it later.
payment.completed example to your address. It checks connectivity but is not queued in the delivery history and is not retried. A non-2xx response makes the test fail at once.POST /v2/webhook-simulate sends a test payment.* event to your subscriptions without a real payment. The list of your subscriptions: GET /v2/webhook-simulate/subscriptions.For the first connectivity check, a temporary receiver such as webhook.site is handy. Do not use a shared test address or a weak secret in production.
Subscriptions are created in the dashboard or through POST /v1/webhooks with a personal token xusr_pat_… (issued in API-ключи (API keys) → “Личные токены” (Personal tokens)). An xapi_… key cannot manage subscriptions: it is for payments. The request body: url, events, secret, description.
The “Вебхуки” (Webhooks) section offers six payment and refund events:
| Event | Condition | Recommended action |
|---|---|---|
payment.completed |
The payment reaches COMPLETED |
Fulfill the order once |
payment.expired |
Kaspi returns CancelledByUser, Expired, or the QR token expired or was discarded |
Release the reservation and offer a new payment |
payment.cancelled |
The payment is cancelled through POST /v2/payments/{payment_id}/cancel, or Kaspi returns Cancelled |
Release the reservation |
payment.failed |
The payment moves to an error status (see below: it is not final) | Record the failure, do not write the order off at once, and let the buyer start a new attempt |
payment.refunded |
A full or partial refund completes through POST /v2/payments/{payment_id}/refund |
Reconcile the order by payment_id |
payment.refund_failed |
The refund could not be completed | Flag the payment for review |
A subscription to * receives all events.
The webhook body is intentionally small. Refund events do not contain a refund_id, the refund amount, or the failure reason: match the payment_id against your own record or request the payment’s refunds with GET /v2/payments/{payment_id}/refunds.
Do not infer the buyer’s action from an event name alone. For example, a rejection that Kaspi sends as CancelledByUser turns into payment.expired, while payment.cancelled means an explicit cancellation or the Kaspi status Cancelled.
payment.failedis not the end of the story. A payment inFAILEDcan still complete asCOMPLETEDif Kaspi later confirms payment. Until a payment reaches a final status, checkGET /v2/payments/{payment_id}. More: Payment statuses and refunds.
If you use online booking with payment, there are separate booking.* events; they arrive only for bookings paid through Kaspi.
All payment and refund events use one envelope:
{
"event": "payment.completed",
"event_version": "1",
"delivery_id": "c09a3647-7822-4899-8401-3857cbd5bf68",
"attempt_number": 1,
"source": "xpayment",
"payment_id": "65cd0d84-5f66-4763-94d2-1b8e1ba68347",
"merchant_order_id": "order-5512",
"created_at": "2026-11-08T10:32:00+05:00",
"environment": "live"
}
| Field | Meaning |
|---|---|
event |
The event type |
event_version |
Payload schema version; currently 1 |
delivery_id |
Stable ID of this delivery across retries |
attempt_number |
Starts at 1 and grows with each retry |
source |
Always xpayment |
payment_id |
The related payment ID in xpayment |
merchant_order_id |
Your order ID; omitted when it was not supplied |
created_at |
When the event was queued (ISO 8601) |
environment |
live for live payments, sandbox for test ones |
Rely on two headers:
Content-Type: application/json
X-xPayment-Signature: aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
X-xPayment-Signature signature against the raw body: Webhook signature verification.delivery_id (see “Idempotent processing” below).GET /v2/payments/{payment_id}. Only it has the amount, the status, and your metadata.2xx.xpayment treats any 2xx response as success. A network error, a 10-second timeout, or a final non-2xx response causes a retry. There are at most three attempts: immediately, about 1 minute after the first failure, and about 5 minutes after the second.
On retries delivery_id does not change and attempt_number grows, so the JSON and its signature change. The order of event delivery is not guaranteed. Return 2xx only after durably accepting the event, and return non-2xx if you want xpayment to retry the delivery.
Add a unique constraint on delivery_id and record it in the same transaction as the business change. In this TypeScript example both operations roll back if fulfillment fails:
await db.transaction(async (tx) => {
const accepted = await tx.webhookReceipts.insertIfAbsent(payload.delivery_id)
if (!accepted) return // already accepted, acknowledge again
const payment = await xpayment.getPayment(payload.payment_id) // GET /v2/payments/{id}
if (payment.status === "COMPLETED") {
await tx.orders.markPaid(payload.merchant_order_id, payload.payment_id)
}
})
return res.status(200).json({ ok: true })
If fulfillment calls an external service, commit a job in the same transaction (an outbox) and run it asynchronously. If one address is listed in several subscriptions, also ensure fulfillment happens once per pair (payment_id, event): each subscription has its own delivery_id.
In the “Вебхуки” section open a subscription to see the latest deliveries. Through the API they are at GET /v1/webhooks/{subscriptionID}/deliveries with a personal token. Delivery statuses are PENDING, SUCCESS, FAILED, and EXHAUSTED; after the last unsuccessful attempt a delivery gets EXHAUSTED. Use the history for diagnostics, not instead of reconciliation in your own system.
Verify X-xPayment-Signature against the exact bytes of the body and the subscription secret before parsing and processing. The algorithm and examples for Node.js, Go, and Python: Webhook signature verification.