xpayment Webhooks: Events, Payloads, and Retries

Configure xpayment webhooks, handle six payment and refund events, verify payloads, retry failures, and process deliveries idempotently.

What a webhook does

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.

Configure a webhook

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.

  1. Open Вебхуки (Webhooks) in the dashboard and select + Новый вебхук (New webhook).
  2. Choose a ready-made integration or enter the URL and an optional description (for example, Production webhook) by hand.
  3. Select the payment and refund events. The interface offers six; selecting all is the safe default.
  4. Set a Secret: a long, random, unique string. The field is technically optional, but without a secret the signature does not protect you: anyone can reproduce it.
  5. Select Создать (Create) and check the connection with the Тест (Test) button.

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.

Checking without live payments

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.

Managing subscriptions through the API

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.

Payment and refund events

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.failed is not the end of the story. A payment in FAILED can still complete as COMPLETED if Kaspi later confirms payment. Until a payment reaches a final status, check GET /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.

Payload and headers

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

What to do on receipt

  1. Verify the X-xPayment-Signature signature against the raw body: Webhook signature verification.
  2. Claim the delivery_id (see “Idempotent processing” below).
  3. Fetch the payment: GET /v2/payments/{payment_id}. Only it has the amount, the status, and your metadata.
  4. Fulfill the order according to the actual payment status.
  5. Reply with 2xx.

Delivery, retries, and idempotency

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.

Idempotent processing

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.

Monitoring delivery

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.

Signature verification

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.

Related guides