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

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

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

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

Коротко:

- платёж проходит путь `PENDING` → `WAITING_FOR_PAYER` → один из итогов;
- итоги `COMPLETED`, `CANCELLED` и `EXPIRED` окончательны;
- **`FAILED` не окончательный:** платёж с таким статусом ещё может стать `COMPLETED`;
- неоплаченный платёж можно отменить, оплаченный можно вернуть (полностью или частично);
- вернуть деньги можно только по платежу, который уже оплачен;
- возврат выполняется в фоне, поэтому его итог приходит вебхуком.

Основной источник правды о статусе — сам платёж: после любого вебхука запросите `GET /v2/payments/{payment_id}`. Про вебхуки подробнее: [Вебхуки xpayment](https://xpayment.kz/blog/webhooks).

## Жизненный цикл платежа

```text
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` в ответе.

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

Основной способ узнать итог — вебхук ([Вебхуки](https://xpayment.kz/blog/webhooks), [Проверка подписи](https://xpayment.kz/blog/webhook-security)). Запасной — опрос `GET /v2/payments/{payment_id}` раз в 3–5 секунд, пока статус не станет окончательным:

```python
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`.

```bash
curl "https://api.xpayment.kz/v2/payments?status=COMPLETED&device_name=Kassa1" \
  -H "Authorization: Bearer xapi_ВАШ_КЛЮЧ"
```

```json
{
  "data": [ /* платежи */ ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMS0wN1QxMDowMDowMFp8dXVpZA=="
}
```

Пока `has_more` равен `true`, передавайте `next_cursor` в параметр `cursor`.

## Отмена платежа

Неоплаченный платёж можно отменить: например, клиент передумал или вы заменили заказ.

```bash
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`, предыдущие неоплаченные ссылки отменяются автоматически и без вебхука. Подробнее: [Платёжные ссылки](https://xpayment.kz/blog/payment-link).

## Возвраты

Вернуть деньги можно по оплаченному платежу: полностью или частями.

```bash
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`

```json
{
  "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](https://xpayment.kz/blog/webhooks). Попробовать возвраты без реальных денег можно в [песочнице](https://xpayment.kz/blog/sandbox): сумма возврата ровно 13.13 ₸ там всегда отклоняется, чтобы вы могли проверить обработку `payment.refund_failed`.

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

- Сохраняйте `refund_id` из ответа `202` и сопоставляйте его с заказом: в вебхуке его не будет.
- Не обещайте клиенту мгновенный возврат: для вас он завершается, когда статус стал `COMPLETED`.
- Если возврат оформляется из кабинета, он также приходит вебхуком и виден в разделе «Транзакции».

## Читайте также
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)
- [Удалённые платежи](https://xpayment.kz/blog/direct-payment)
- [sandbox](https://xpayment.kz/blog/sandbox)

---

Источник: https://xpayment.kz/blog/payment-statuses-and-refunds
