# Статус инвойса и депозита

Проверка инвойса или депозита через API — с вебхуками или без них.

Source: https://docs.invoise.me/ru/payments/status/

Запрашивайте состояние инвойса или депозита через GET. Вебхуки уведомляют об изменениях автоматически.

## Получите инвойс или депозит

Используйте `id` из ответа на создание инвойса или депозита:

```bash
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'
```

Важные поля примера ответа (остальные опущены):

```json
{
  "id": "f06b8a31-19c7-4687-ade3-1c09466d2751",
  "kind": "invoice",
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "token_decimals": 6,
  "expires_at": "2026-10-19T10:00:00Z",
  "cancelled_at": null,
  "disabled_at": null,
  "payout_tx_hash": null
}
```

Обе суммы — целочисленные строки в минимальных единицах. Здесь пришло 10 токенов, но подтверждённой транзакции пейаута ещё нет.

## Как читать статус инвойса

| `status` | Что делать |
| --- | --- |
| `registering` | Дождитесь непустого `address`. Не вычисляйте адрес сами. |
| `open` | Ждите оплату. В `received` уже может быть частичная сумма. |
| `funded` | Подтверждённых средств достаточно для пейаута. |
| `settled` | Инвойс закрыт в блокчейне. |
| `reconciling` | Дождитесь сверки; не считайте платёж успешным. |

Отдельно проверяйте `cancelled_at`: это дата или `null`, а не значение статуса. Поле заполняется, когда вы отменяете инвойс, когда неоплаченный инвойс доходит до `expires_at` или когда сотрудники Invoise блокируют мерчанта; вебхук `invoice.cancelled` различает эти случаи по [`data.reason`](https://docs.invoise.me/ru/integration/webhooks/#2-выберите-события). Отмена скрывает checkout, но не останавливает переводы и пейаут. Заранее решите, что делать с оплаченным отменённым инвойсом.

`funded` означает получение оплаты, а не завершение пейаута. `settled` фиксирует закрытие инвойса. Полный учёт пейаута подтверждает `payout.confirmed`; `payout_tx_hash`, если он есть, указывает на последний подтверждённый перевод получателю.

Если получен `transfer.reverted`, Invoise сообщает об отмене конкретного входящего перевода в сети. Найдите его по `chain_event.reference_event_id`, запросите актуальное состояние инвойса и скорректируйте учёт этого перевода один раз. Формат события описан в [вебхуках](https://docs.invoise.me/ru/integration/webhooks/).

## Как следить за депозитом

Депозитный адрес многоразовый. После пейаута он может вернуться в `open`, поэтому не ждите постоянного `settled`.

`received` — **вся подтверждённая входящая сумма**, а не остаток. Пейаут её не уменьшает. Отмена перевода при реорганизации может уменьшить. Зачисляйте каждый входящий платёж один раз; для этого удобны вебхуки со стабильным ID события.

`disabled_at` управляет доступностью checkout. Отключение депозита не прекращает наблюдение за адресом.

## Получите список инвойсов и депозитов

```bash
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'
```

С `limit` от 1 до 100 ответ имеет вид `{"items":[...],"next_cursor":"..."}`. Для следующей страницы передайте `cursor`; пустой `next_cursor` означает конец. Без параметров пагинации приходит ограниченный массив, а не вся история.

Есть фильтры `kind`, `status` и `q`. Фильтр списка `status=paid` выбирает `funded` и `settled`. Сам GET инвойса или депозита не возвращает статус `paid`.

Поле `transfers` в ответе инвойса или депозита содержит только десять последних подтверждённых входящих переводов и пейаутов. Это не полный журнал.

## Публичный статус checkout

`GET /api/v1/checkout/{public_id}` работает без ключа. Он отдаёт состояние страницы оплаты, в том числе `status`, `received`, `amount` и `expires_at`. Для записей магазина на вашем бэкенде используйте авторизованный GET инвойса или депозита.

Автоматические уведомления и проверка подписи описаны в [вебхуках](https://docs.invoise.me/ru/integration/webhooks/).