Жизненный цикл платежа, почему FAILED не окончательный статус, как отменить неоплаченный платёж и сделать полный или частичный возврат.
Создать платёж — полдела. Чтобы корректно выполнить заказ, отменить неоплаченный счёт или вернуть деньги, нужно понимать, какие статусы бывают у платежа, какие из них окончательные и что происходит после оплаты. Эта статья собирает всё в одном месте для API v2.
Коротко:
PENDING → WAITING_FOR_PAYER → один из итогов;COMPLETED, CANCELLED и EXPIRED окончательны;FAILED не окончательный: платёж с таким статусом ещё может стать COMPLETED;Основной источник правды о статусе — сам платёж: после любого вебхука запросите GET /v2/payments/{payment_id}. Про вебхуки подробнее: Вебхуки xpayment.
PENDING
└─► WAITING_FOR_PAYER (покупатель открыл счёт или ссылку)
├─► COMPLETED (покупатель оплатил)
├─► CANCELLED (отменён вами или Kaspi)
└─► EXPIRED (время вышло или покупатель не подтвердил)
└─► CANCELLING (отмена запрошена, ждём подтверждения Kaspi)
└─► FAILED (пока не окончательный, см. ниже)
├─► COMPLETED (Kaspi позже подтвердил оплату)
├─► CANCELLED / EXPIRED
└─► FAILED (остаётся FAILED, когда срок платежа истёк)
COMPLETED
└─► PARTIALLY_REFUNDED (завершён хотя бы один возврат)
└─► REFUNDED (возвращена вся сумма)
| Статус | Что означает | Окончательный? |
|---|---|---|
PENDING |
Платёж создан, ждёт | Нет |
WAITING_FOR_PAYER |
Покупатель видит счёт или открыл ссылку | Нет |
CANCELLING |
Вы запросили отмену, Kaspi ещё не подтвердил | Нет |
COMPLETED |
Покупатель оплатил | Да (дальше возможны возвраты) |
CANCELLED |
Платёж отменён | Да |
EXPIRED |
Время вышло, либо покупатель не подтвердил | Да |
FAILED |
Kaspi отклонил платёж или ответил непонятно | Нет |
PARTIALLY_REFUNDED |
Часть суммы возвращена | Расчёт по платежу завершён |
REFUNDED |
Возвращена вся сумма | Да |
Для фильтра status в списках используйте заглавные буквы, как в ответе (COMPLETED, а не completed).
FAILED не конецИстина о платеже находится в Kaspi, и xpayment продолжает спрашивать Kaspi, пока платёж не завершится или не истечёт срок его жизни. FAILED можно получить, когда ответ Kaspi временно непонятен или когда Kaspi отклоняет платёж, который покупатель затем повторяет. Позже тот же платёж может стать COMPLETED, и вебхук payment.completed придёт для платежа, который ваша система уже списала.
Поэтому:
FAILED или payment.failed;FAILED статусом «пока не оплачено»;COMPLETED, CANCELLED или EXPIRED. Это всегда происходит в пределах срока жизни платежа: самое позднее через сутки.POST /v2/payments) действует до 24 часов, это ограничение Kaspi.POST /v2/payments/link) живёт заметно короче: ориентируйтесь на expire_date в ответе.Основной способ узнать итог — вебхук (Вебхуки, Проверка подписи). Запасной — опрос GET /v2/payments/{payment_id} раз в 3–5 секунд, пока статус не станет окончательным:
import os, time
import httpx
API = "https://api.xpayment.kz/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"}
# FAILED сознательно отсутствует: он обратим.
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 возвращает платежи постранично (по 20) с курсором. Фильтры: status, payer_phone, merchant_order_id, device_name (регистр не важен, включает платежи прежних касс с этим именем) и cursor.
curl "https://api.xpayment.kz/v2/payments?status=COMPLETED&device_name=Kassa1" \
-H "Authorization: Bearer xapi_ВАШ_КЛЮЧ"
{
"data": [ /* платежи */ ],
"has_more": true,
"next_cursor": "MjAyNi0xMS0wN1QxMDowMDowMFp8dXVpZA=="
}
Пока has_more равен true, передавайте next_cursor в параметр cursor.
Неоплаченный платёж можно отменить: например, клиент передумал или вы заменили заказ.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/cancel \
-H "Authorization: Bearer xapi_ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"reason": "Клиент передумал"}'
Поле reason необязательное. В ответе 200 придёт обновлённый платёж со статусом CANCELLING (ждём подтверждения Kaspi) или сразу CANCELLED; итог придёт вебхуком payment.cancelled.
Отменить можно, пока платёж не завершился: в статусах PENDING, WAITING_FOR_PAYER и даже FAILED (он ещё под наблюдением, потому что может оплатиться). Когда исход платежа уже известен, отмена возвращает 409 PAYMENT_NOT_CANCELABLE.
Это относится и к гонке: если покупатель успел оплатить между вашим чтением и запросом на отмену, побеждает факт оплаты, а отмена будет отклонена. Деньги в такой ситуации возвращаются отдельным возвратом (следующий раздел).
Если вы создаёте новую ссылку для того же
merchant_order_id, предыдущие неоплаченные ссылки отменяются автоматически и без вебхука. Подробнее: Платёжные ссылки.
Вернуть деньги можно по оплаченному платежу: полностью или частями.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/refund \
-H "Authorization: Bearer xapi_ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"amount": 500, "reason": "Товар возвращён"}'
| Поле | Обязательное | Описание |
|---|---|---|
amount |
да | Больше нуля и не больше остатка, который ещё можно вернуть |
reason |
нет | Причина возврата |
COMPLETED и PARTIALLY_REFUNDED. Для остальных API вернёт 409 PAYMENT_NOT_REFUNDABLE.202 Accepted со статусом PENDING означает, что запрос принят, а не что деньги уже вернулись.PARTIALLY_REFUNDED, после возврата всей суммы — REFUNDED.202{
"refund_id": "2a7c0f6e-6c87-4d0d-8a5a-0d6f4a3b9c11",
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"amount": 500.00,
"reason": "Товар возвращён",
"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 или FAILED. Оба последних окончательны. В fail_reason указана причина, если возврат не удался.
| Статус | Что означает |
|---|---|
PENDING |
Возврат принят и ждёт обработки |
PROCESSING |
Возврат выполняется |
COMPLETED |
Деньги вернулись покупателю |
FAILED |
Возврат не удалось выполнить |
Вебхуки: payment.refunded (возврат завершён) и payment.refund_failed (не удался). В них нет refund_id и суммы возврата, поэтому сверьтесь через API:
| Запрос | Что вернёт |
|---|---|
GET /v2/payments/{payment_id}/refunds |
Возвраты одного платежа |
GET /v2/refunds |
Все возвраты, фильтры payment_id, status и cursor |
GET /v2/refunds/{refundID} |
Один возврат |
Подробнее про вебхуки: Вебхуки xpayment. Попробовать возвраты без реальных денег можно в песочнице: сумма возврата ровно 13.13 ₸ там всегда отклоняется, чтобы вы могли проверить обработку payment.refund_failed.
refund_id из ответа 202 и сопоставляйте его с заказом: в вебхуке его не будет.COMPLETED.