Статусы платежей, отмена и возвраты в API v2

Жизненный цикл платежа, почему FAILED не окончательный статус, как отменить неоплаченный платёж и сделать полный или частичный возврат.

Что нужно знать о статусах и возвратах

Создать платёж — полдела. Чтобы корректно выполнить заказ, отменить неоплаченный счёт или вернуть деньги, нужно понимать, какие статусы бывают у платежа, какие из них окончательные и что происходит после оплаты. Эта статья собирает всё в одном месте для API v2.

Коротко:

Основной источник правды о статусе — сам платёж: после любого вебхука запросите 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 придёт для платежа, который ваша система уже списала.

Поэтому:

Сколько живёт платёж

Вебхук или опрос

Основной способ узнать итог — вебхук (Вебхуки, Проверка подписи). Запасной — опрос 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 нет Причина возврата

Что нужно знать

Ответ 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.

Практические советы