Сценарий для агента

Это настройка для агента с сессией кошелька. Если ID магазина и API-ключ уже есть, переходите сразу к шагу 4.

Каждому JSON-запросу на изменение ниже нужны Content-Type: application/json, bearer-токен сессии и сохранённый Idempotency-Key, уникальный для действия.

1. Выберите мерчанта

Прочитайте GET /api/v1/me. Если user.onboarding_required равен true, сначала спросите у своего человека его email, затем завершите настройку:

POST /api/v1/onboarding
Content-Type: application/json

{"name":"My merchant","email":"[email protected]"}

Аккаунт, вошедший только кошельком, должен передать email; без него ответ — 400 email_required. Некорректный адрес вернёт invalid_email, одноразовый — disposable_email, а email, который уже принадлежит другому аккаунту, — identity_already_linked. Email становится способом входа в этот же аккаунт. Invoise отправляет человеку уведомление: он открывает интерфейс, входит с этим email по одноразовому коду и попадает в созданный вами аккаунт.

Ответ {"completed":true} не содержит ID мерчанта. После него вызовите GET /api/v1/merchants и сохраните id нужного мерчанта.

У существующего аккаунта их может быть несколько. Выберите нужного явно, а не берите первый элемент. Не используйте POST /merchants для первичной настройки: он возвращает forbidden.

2. Создайте магазин

POST /api/v1/merchants/{merchant_id}/shops
Content-Type: application/json

{
  "name": "Agent payments",
  "sandbox": true,
  "recipient": "<your-payout-address>"
}

Сохраните id ответа как shop_id. Для теста начните с Sandbox; затем создайте отдельный боевой магазин с sandbox: false.

Необязательный EVM-делегат delegate нужен только для независимого завершения инвойса вашим кошельком. Адрес биржи для этой роли не подходит.

Получателя и делегата можно изменить позже через PATCH /api/v1/shops/{shop_id}. Уже созданные инвойсы и адреса сохраняют значения на момент создания.

Боевой магазин может вместо этого платить в кошелёк Invoise аккаунта: передайте "payout_target":"wallet" без recipient. Кошелёк настраивает ваш человек в интерфейсе; до этого создание инвойса вернёт 400 wallet_not_ready. Для Solana и Tron нужен отдельный получатель; см. Solana и Tron.

3. Выпустите API-ключ магазина

С токеном сессии создайте ключ с read и write. Сохраните ivk_-токен в хранилище секретов и используйте его для дальнейших платёжных запросов.

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

1. Прочитайте GET /api/v1/networks. Выберите включённую сеть и готовый токен с его настоящим адресом и числом знаков.
2. Сохраните ключ идемпотентности рядом с инвойсом в вашей системе до отправки запроса.
3. Вызовите POST /api/v1/shops/{shop_id}/invoices:

Поле	Значение
chain_id	ID выбранной сети из API; целое число.
token	Адрес выбранного токена из API.
amount	Сумма инвойса в минимальных единицах токена; строка целого числа.
external_id	Необязательная ссылка на запись в вашей системе.

Для многоразового адреса пополнения вызовите /deposits без amount. Чтобы плательщик выбрал один из нескольких токенов или сетей, передайте assets вместо chain_id и token; см. Депозиты и инвойсы.

После таймаута повторяйте тот же запрос с тем же ключом. Один external_id не защищает от дублей.

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

Сохраните id из ответа 202. Опрашивайте:

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

Дождитесь непустого address, затем передайте payment_url. Продолжайте читать status и received через тот же endpoint. Получайте уведомления об изменениях через вебхуки.

Перед учётом оплаты инвойса прочитайте Статус инвойса и депозита: funded, settled, отмена и многоразовые депозиты имеют разный смысл. Каждое изменение бизнес-данных сохраняйте один раз.

Читайте документацию без браузера

llms.txt содержит индекс страниц, OpenAPI — формальные контракты. Markdown и полный текст описаны в чтении документации.