Payment Statuses, Cancellation, and Refunds in API v2

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.

What you need to know about statuses and refunds

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:

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.

The payment lifecycle

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

Why FAILED is not the end

The 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:

How long a payment lives

A webhook or polling

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

Listing payments

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.

Cancelling a payment

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.

Refunds

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

What to know

Response 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
}

Refund statuses

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

How to learn the result

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.

Practical tips