Перейти к содержимому

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

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

Окно терминала
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 связывает инвойс с заказом в вашей системе и не заменяет ключ идемпотентности.

Необязательные поля: description (до 500 символов), external_id (до 200) и return_url, который должен быть адресом https://. Слишком длинные description или external_id вернут 400 invalid_description, другой return_url — 400 invalid_return_url. Депозиты принимают те же поля.

Ответ — 202 Accepted, и в нём уже есть платёжный address и payment_url; инвойс сразу в статусе open. Сохраните id и передайте плательщику вернувшийся payment_url. Если пришёл 503 address_unavailable, повторите тот же запрос с тем же Idempotency-Key.

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

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

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

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

У депозитов срока нет. Если передать 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": "open",
"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": "<option-address>",
"status": "open"
}
],
"expires_at": "2026-10-19T09:00:00Z"
}

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

Группа-инвойс оплачивается один раз. Её 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 активных инвойсов и до 100 000 активных депозитных адресов в сетях EVM, 100 000 в Tron и 100 в Solana, а новых адресов для оплаты за час он может создать не больше, чем его лимит активных инвойсов. Чтобы освободить место, отмените ненужные инвойсы или отключите ненужные депозиты. Это значения по умолчанию: сотрудники Invoise могут задать мерчанту другие лимиты. Чтобы обслуживать больше плательщиков, отключайте простаивающие депозиты и включайте их снова, когда они понадобятся: отключённый депозит не занимает место в лимите, а для повторного включения нужно свободное место. Отключённый адрес по-прежнему отслеживается, поэтому деньги, пришедшие на него позже, всё равно зачисляются и выплачиваются. Отключённый адрес Solana, на который час ничего не приходило, проверяется раз в час, поэтому такие деньги видны с задержкой до часа; не отключайте адрес, на который ещё ждёте оплату. Какие адреса переключать, решаете вы; переключать может и API-ключ магазина с правом write. Точные значения и коды ошибок — в разделе Лимиты.

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

Оба действия доступны API-ключу магазина с правом write и сессии владельца; нужен сохранённый Idempotency-Key.

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

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

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