Депозиты и инвойсы

Для заказа с фиксированной ценой создайте инвойс. Для баланса клиента, который можно пополнять много раз, — депозит.

Создать инвойс

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\",\"external_id\":\"order-123\"}"

Замените {shop_id} на ID магазина. Задайте CHAIN_ID и TOKEN_ADDRESS по ответу API, а AMOUNT — в минимальных единицах выбранного токена. external_id связывает инвойс с заказом в вашей системе и не заменяет ключ идемпотентности.

Ответ — 202 Accepted. Сохраните id и опрашивайте статус инвойса, пока не появится address. Затем передайте плательщику вернувшийся payment_url.

Частичные оплаты складываются. Когда подтверждённых средств достаточно, Invoise отправляет пейаут и закрывает инвойс. Получателю уходит сумма инвойса минус комиссия. Переплата уходит Invoise, а не получателю.

Инвойс одноразовый: автоматического продления нет.

Срок действия инвойса

По умолчанию инвойс открыт 30 дней. Чтобы выбрать другой срок, добавьте в тело запроса expires_in, например "expires_in":"7d". Допустимые значения: 1d, 7d, 30d, 180d и 365d.

Ответы с инвойсом, в том числе публичный checkout, содержат expires_at. Когда срок истекает, неоплаченный инвойс закрывается: заполняется cancelled_at и отправляется вебхук invoice.cancelled с data.reason, равным expired. Оплата, пришедшая позже, всё равно учитывается и может уйти в пейаут, как у отменённого инвойса.

У депозитов срока нет. Если передать expires_in при создании депозита, придёт 400 invalid_expires_in.

Создать депозитный адрес

С теми же заголовками отправьте запрос на другой путь:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/deposits' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"external_id\":\"customer-123\"}"

Фиксированный amount не нужен. Дождитесь адреса так же, как для инвойса. На него можно многократно отправлять выбранный токен в выбранной сети.

Небольшие переводы накапливаются до порога пейаута магазина. Получите его через GET /api/v1/shops/{shop_id}/terms.

Несколько токенов или сетей

Передайте assets вместо chain_id и token, чтобы плательщик сам выбрал, чем платить. Это работает для инвойсов и депозитов:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d '{"assets":[{"chain_id":<chain-id>,"token":"<token-address>"},{"chain_id":<other-chain-id>,"token":"<other-token-address>"}],"amount":"10.5","external_id":"order-124"}'

С assets сумма инвойса amount — десятичная сумма в токенах, например "10.5", а не минимальные единицы: у токенов может быть разное число знаков. Каждый вариант должен достигать minimum_payment своей сети.

Ответ — группа. Каждый вариант — отдельный инвойс или депозитный адрес со своим address, суммой в минимальных единицах и статусом:

{
  "id": "<group-id>",
  "group": true,
  "shop_id": "<shop-id>",
  "public_id": "<public-id>",
  "status": "registering",
  "payment_url": "https://pay.invoise.me/<public-id>",
  "options": [
    {
      "id": "<option-id>",
      "public_id": "<option-public-id>",
      "chain_id": 12345,
      "token": "<token-address>",
      "token_decimals": 6,
      "family": "evm",
      "amount": "10500000",
      "address": null,
      "status": "registering"
    }
  ],
  "expires_at": "2026-10-19T09:00:00Z"
}

Сохраните id группы. GET /api/v1/shops/{shop_id}/issuances/{id} возвращает группу со всеми вариантами; опрашивайте его, пока у вариантов не появятся адреса, затем передайте плательщику payment_url группы — там он выберет вариант.

Группа-инвойс оплачивается один раз. Её status берётся у оплаченного варианта, а paid_issuance_id указывает на него. Вебхуки приходят по каждому варианту и содержат group_id и group_public_id. duplicate: true означает, что группа уже оплачена другим вариантом: не засчитывайте заказ дважды. У группы-депозита остаётся по одному многоразовому адресу на вариант.

Отменяйте группу-инвойс или отключайте группу-депозит по id группы: все варианты меняются вместе. id отдельного варианта вернёт 400 issuance_in_group.

Если хотя бы один вариант создать нельзя, не создаётся ничего, а error.details указывает вариант как {chain_id, token}. Пустая или повторённая пара, а также assets вместе с chain_id или token вернут 400 invalid_assets.

Лимиты

Сумма одного инвойса — не больше 1 000 000 токенов. У мерчанта может быть до 2 000 активных инвойсов и ограниченное число активных депозитных адресов в каждом семействе сетей. Чтобы освободить место, отмените ненужные инвойсы или отключите ненужные депозиты. Точные значения и коды ошибок — в разделе Лимиты.

Отключить депозит или отменить инвойс

Действие	Запрос
Отключить страницу депозита	PATCH /api/v1/shops/{shop_id}/deposits/{id} с {"enabled":false}. Для включения передайте true.
Отменить страницу инвойса	POST /api/v1/shops/{shop_id}/invoices/{id}/cancel.

Для обоих действий нужны авторизация и сохранённый Idempotency-Key.

Эти действия закрывают страницу оплаты. Они не возвращают деньги и не прекращают наблюдение за адресом. Средства на отменённом инвойсе всё ещё могут уйти в пейаут; его события содержат invoice_cancelled: true.

Переводы после завершения инвойса учитываются как поздние и автоматически не выплачиваются. Их восстановление, как и восстановление ошибочно отправленного токена, требует отдельной ручной операции.

Все поля запросов и ответов — в справочнике API.