Быстрый старт

Хотите подключиться быстрее? Скопируйте промпт и передайте своему агенту — он поможет настроить магазин и проверить первый инвойс.

Помоги подключить Invoise к моему проекту. Прочитай https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json и https://docs.invoise.me/ru/agents/integration.md.

Используй существующий доступ или помоги пройти вход, создать мерчанта, магазин и API-ключ. Если входишь кошельком, спроси мой email до создания мерчанта. Уточни у меня адрес получателя до создания магазина. Получай доступные сети, токены, decimals и комиссии из API.

Начни с Sandbox: создай инвойс, получи payment_url, подключи вебхуки с проверкой подписи и защитой от повторов, проверь оплату через GET. Сохраняй Idempotency-Key до запросов. В конце покажи результат проверки и что нужно для приёма реальных платежей.

Это обычный способ подключить Invoise к сайту или бэкенду: человек входит в интерфейс, настраивает магазин, а сервер дальше работает с API по ключу.

Делаете агента, который работает без браузера и без почты? Вам в раздел Вход агента. Эта страница исходит из того, что настройку делает человек.

1. Войдите и создайте магазин

Откройте platform.invoise.me и войдите по коду на почту или через Google. При первом входе создаётся мерчант; магазинов у него ещё нет, поэтому создайте один.

Магазину нужен получатель — кошелёк, на который приходят деньги, — либо магазин платит в ваш кошелёк Invoise. Получателя и необязательного делегата можно изменить позже; уже созданные инвойсы и адреса сохраняют значения на момент создания.

Хотите потренироваться без реальных средств — создайте sandbox-магазин. См. Sandbox.

2. Создайте API-ключ

В магазине создайте ключ с правами read и write. Он начинается с ivk_ и показывается один раз, поэтому сохраните его сразу.

Сервер передаёт его в каждом запросе:

Authorization: Bearer ivk_...

Ключ работает только для одного магазина и не может тронуть аккаунт или команду. См. API-ключи.

3. Выберите сеть и токен

curl https://platform.invoise.me/api/v1/networks

Возьмите chain_id, адрес токена и decimals из ответа. Выберите сеть, включённую для мерчанта, и готовый токен. Доступные активы меняются; не зашивайте их список в код. См. Сети и токены.

4. Создайте инвойс

Суммы — целочисленные строки в минимальных единицах токена. При 6 знаках 10000000 — это 10 токенов.

Перед запросом задайте переменные окружения:

Переменная	Значение
`CHAIN_ID`	`chain_id` выбранной сети из API.
`TOKEN_ADDRESS`	`tokens[].address` выбранного токена в этой сети.
`AMOUNT`	Сумма инвойса в минимальных единицах, рассчитанная по `tokens[].decimals`.

curl -X POST https://platform.invoise.me/api/v1/shops/{shop_id}/invoices \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2a8b1f47-6d0c-4a1f-8f0b-4f2c9f3a77d2' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\"}"

Замените {shop_id} на ID магазина. Создайте и сохраните уникальный Idempotency-Key для этого инвойса; ключ в примере — только образец.

В ответе 202 Accepted сохраните id как issuance_id. Код 202 означает принятие запроса на создание, а не оплату клиентом.

Нужен многоразовый адрес для пополнений без фиксированной суммы? Вызовите /deposits. См. Депозиты и инвойсы.

5. Дождитесь адреса

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

Опрашивайте, пока не вернётся адрес, и отправьте плательщика на payment_url из этого ответа. Это готовая платёжная страница — адрес, QR-код и статус там уже есть.

6. Проверьте оплату

Инвойс оплачен, когда его status — funded или settled. При funded нужная сумма уже подтверждена, при settled инвойс закрыт в блокчейне. Статус можно получить через API, а об изменении узнать через вебхук.

Через вебхук

До первого платежа зарегистрируйте адрес вашего сервера:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-webhook-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Замените URL на свой публичный HTTPS-адрес и сохраните secret из ответа.

При получении события проверьте Invoise-Signature с этим секретом и отсейте повторы по Invoise-Event-ID. Пример проверки подписи.
transfer.confirmed сообщает о подтверждённом входящем переводе. Возьмите data.issuance_id и запросите статус инвойса через GET ниже: один перевод может покрывать лишь часть суммы.
Если status — funded или settled и cancelled_at равен null, учтите оплату инвойса в вашей системе один раз. Событие payout.confirmed отдельно подтверждает полный учёт пейаута получателю.

Через API

Запросите состояние инвойса с вашего сервера:

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

Важные поля ответа при оплате:

{
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "cancelled_at": null
}

Здесь вся сумма инвойса подтверждена. Учтите оплату инвойса в вашей системе; повторный GET или вебхук не должен зачислить его второй раз.

При open продолжайте ждать: оплата ещё не пришла полностью. Можно опрашивать раз в 3–5 секунд и увеличивать интервал при долгом ожидании. registering и reconciling также не означают успех. Если cancelled_at заполнен, обработайте оплату отменённого инвойса отдельно.

Все состояния и особенности депозитов — в статусе инвойса и депозита.

Одно правило, которое стоит запомнить

Создание инвойса или депозита требует Idempotency-Key. Сохраните ключ: если запрос отвалился по таймауту и непонятно, прошёл он или нет, отправьте тот же запрос с тем же ключом. Вернётся исходный результат, а не второй инвойс. См. Идемпотентность и ошибки.