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

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

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

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

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

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

{
  "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. Отмена скрывает checkout, но не останавливает переводы и пейаут. Заранее решите, что делать с оплаченным отменённым инвойсом.

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

Если получен transfer.reverted, Invoise сообщает об отмене конкретного входящего перевода в сети. Найдите его по chain_event.reference_event_id, запросите актуальное состояние инвойса и скорректируйте учёт этого перевода один раз. Формат события описан в вебхуках.

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

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

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

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

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

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 инвойса или депозита.

Автоматические уведомления и проверка подписи описаны в вебхуках.