Депозиты и инвойсы
Для заказа с фиксированной ценой создайте инвойс. Для баланса клиента, который можно пополнять много раз, — депозит.
Создать инвойс
Заголовок раздела «Создать инвойс»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.