The payment lifecycle, why FAILED is not a final status, how to cancel an unpaid payment, and how to make a full or partial refund.
Creating a payment is only half the job. To fulfill an order correctly, cancel an unpaid invoice, or return money, you need to understand which statuses a payment has, which of them are final, and what happens after payment. This article gathers it all in one place for API v2.
In short:
PENDING → WAITING_FOR_PAYER → one of the outcomes;COMPLETED, CANCELLED, and EXPIRED are final;FAILED is not final: a payment with that status can still become COMPLETED;The main source of truth about status is the payment itself: after any webhook, fetch GET /v2/payments/{payment_id}. More about webhooks: xpayment webhooks.
PENDING
└─► WAITING_FOR_PAYER (the buyer opened the invoice or link)
├─► COMPLETED (the buyer paid)
├─► CANCELLED (cancelled by you or Kaspi)
└─► EXPIRED (time ran out or the buyer did not confirm)
└─► CANCELLING (cancellation requested, waiting for Kaspi)
└─► FAILED (not final yet, see below)
├─► COMPLETED (Kaspi later confirmed payment)
├─► CANCELLED / EXPIRED
└─► FAILED (stays FAILED when the payment's time is over)
COMPLETED
└─► PARTIALLY_REFUNDED (at least one refund completed)
└─► REFUNDED (the full amount was returned)
| Status | What it means | Final? |
|---|---|---|
PENDING |
The payment is created and waiting | No |
WAITING_FOR_PAYER |
The buyer sees the invoice or opened the link | No |
CANCELLING |
You requested cancellation, Kaspi has not confirmed it yet | No |
COMPLETED |
The buyer paid | Yes (refunds are still possible) |
CANCELLED |
The payment is cancelled | Yes |
EXPIRED |
Time ran out, or the buyer did not confirm | Yes |
FAILED |
Kaspi rejected the payment or answered unclearly | No |
PARTIALLY_REFUNDED |
Part of the amount was returned | Settlement of the payment is complete |
REFUNDED |
The full amount was returned | Yes |
For the status filter in lists, use capital letters as in the response (COMPLETED, not completed).
FAILED is not the endThe truth about a payment lives in Kaspi, and xpayment keeps asking Kaspi until the payment completes or its lifetime ends. You can get FAILED when Kaspi’s response is temporarily unclear, or when Kaspi rejects a payment that the buyer then retries. Later the same payment can become COMPLETED, and the payment.completed webhook arrives for a payment your system has already written off.
So:
FAILED or payment.failed;FAILED as “not paid yet”;COMPLETED, CANCELLED, or EXPIRED. This always happens within the payment’s lifetime: a day at most.POST /v2/payments) lasts up to 24 hours; this is a Kaspi limit.POST /v2/payments/link) lives noticeably shorter: go by expire_date in the response.The main way to learn the outcome is a webhook (Webhooks, Signature verification). The fallback is polling GET /v2/payments/{payment_id} every 3–5 seconds until the status is final:
import os, time
import httpx
API = "https://api.xpayment.kz/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"}
# FAILED is deliberately absent: it is reversible.
FINAL = {"COMPLETED", "CANCELLED", "EXPIRED", "REFUNDED"}
def wait_for_payment(payment_id: str, timeout_sec: int = 120) -> dict:
deadline = time.time() + timeout_sec
while time.time() < deadline:
resp = httpx.get(f"{API}/payments/{payment_id}", headers=HEADERS, timeout=15)
resp.raise_for_status()
payment = resp.json()
if payment["status"] in FINAL:
return payment
time.sleep(4)
raise TimeoutError(f"payment {payment_id} did not reach a final status in {timeout_sec}s")
GET /v2/payments returns payments page by page (20 each) with a cursor. Filters: status, payer_phone, merchant_order_id, device_name (case-insensitive, includes payments of earlier registers with this name), and cursor.
curl "https://api.xpayment.kz/v2/payments?status=COMPLETED&device_name=Kassa1" \
-H "Authorization: Bearer xapi_YOUR_KEY"
{
"data": [ /* payments */ ],
"has_more": true,
"next_cursor": "MjAyNi0xMS0wN1QxMDowMDowMFp8dXVpZA=="
}
While has_more is true, pass next_cursor in the cursor parameter.
An unpaid payment can be cancelled: for example, the customer changed their mind or you replaced the order.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/cancel \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "The customer changed their mind"}'
The reason field is optional. The 200 response contains the updated payment with status CANCELLING (waiting for Kaspi’s confirmation) or immediately CANCELLED; the result arrives by the payment.cancelled webhook.
You can cancel while the payment has not settled: in PENDING, WAITING_FOR_PAYER, and even FAILED (it is still under observation because it may yet be paid). When the outcome of the payment is already known, cancelling returns 409 PAYMENT_NOT_CANCELABLE.
The same holds for a race: if the buyer managed to pay between your read and your cancel request, the fact of payment wins and the cancellation is rejected. In that situation the money is returned by a separate refund (the next section).
If you create a new link for the same
merchant_order_id, the earlier unpaid links are cancelled automatically and without a webhook. More: Payment links.
You can return money for a paid payment: in full or in parts.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/refund \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 500, "reason": "Product returned"}'
| Field | Required | Description |
|---|---|---|
amount |
yes | Greater than zero and not more than the remainder that can still be returned |
reason |
no | The reason for the refund |
COMPLETED and PARTIALLY_REFUNDED. For others the API returns 409 PAYMENT_NOT_REFUNDABLE.202 Accepted with status PENDING means the request is accepted, not that the money has already come back.PARTIALLY_REFUNDED, and after the whole amount is returned, REFUNDED.202{
"refund_id": "2a7c0f6e-6c87-4d0d-8a5a-0d6f4a3b9c11",
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"amount": 500.00,
"reason": "Product returned",
"status": "PENDING",
"fail_reason": null,
"created_at": "2026-11-08T10:05:00Z",
"updated_at": "2026-11-08T10:05:00Z",
"completed_at": null
}
PENDING → PROCESSING → COMPLETED or FAILED. The last two are final. fail_reason gives the reason if the refund failed.
| Status | What it means |
|---|---|
PENDING |
The refund is accepted and waits for processing |
PROCESSING |
The refund is being carried out |
COMPLETED |
The money returned to the buyer |
FAILED |
The refund could not be carried out |
Webhooks: payment.refunded (the refund is complete) and payment.refund_failed (it failed). They have no refund_id and no refund amount, so reconcile through the API:
| Request | What it returns |
|---|---|
GET /v2/payments/{payment_id}/refunds |
The refunds of one payment |
GET /v2/refunds |
All refunds, filters payment_id, status, and cursor |
GET /v2/refunds/{refundID} |
One refund |
More about webhooks: xpayment webhooks. You can try refunds without real money in the sandbox: a refund of exactly 13.13 ₸ is always declined there, so you can check how you handle payment.refund_failed.
refund_id from the 202 answer and match it with the order: the webhook will not have it.COMPLETED.