Швидкий старт

Скопіюйте цей промпт у свого агента, щоб налаштувати магазин і перевірити перший рахунок.

Help me integrate Invoise into my project. Read https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json and https://docs.invoise.me/agents/integration.md.

Use my existing access or help me sign in and create a merchant, shop and API key. If you sign in with a wallet, ask me for my email before creating the merchant. Ask me for the recipient address before creating the shop. Read available networks, tokens, decimals and fees from the API.

Start in Sandbox: create an invoice, get payment_url, connect webhooks with signature verification and deduplication, and check payment through GET. Save Idempotency-Key before sending requests. Finish with the test result and what is needed to accept real payments.

Це звичайний спосіб інтегрувати Invoise у сайт чи бекенд: увійдіть як людина, налаштуйте магазин у кабінеті, а потім нехай ваш сервер звертається до API з ключем.

Створюєте автономного агента без браузера й пошти? Перейдіть до Входу для агента — ця сторінка розрахована на те, що налаштування виконує людина.

1. Увійдіть і створіть магазин

Відкрийте platform.invoise.me і увійдіть за кодом з email або через Google. Під час першого входу ви створюєте мерчанта; у нового мерчанта ще немає магазинів, тож створіть один.

Магазину потрібен отримувач — гаманець, що отримує ваші гроші, — або виплати у ваш гаманець Invoise. Отримувача та опціонального делегата можна змінити пізніше; вже створені рахунки й адреси зберігають ті, з якими їх створили.

Створіть магазин у пісочниці, якщо хочете потренуватися без реальних коштів. Див. Пісочницю.

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. Зберігайте ключ: якщо запит завершився таймаутом і ви не впевнені, чи він спрацював, надішліть той самий запит з тим самим ключем знову. Ви отримаєте початковий результат замість другого рахунку. Див. Ідемпотентність і помилки.