Вебхуки
Вебхук — це HTTP-запит, який Invoise надсилає на ваш сервер, коли змінюється платіж. Можна почати з перевірок статусу через GET і додати вебхуки, коли знадобляться автоматичні оновлення.
1. Зареєструйте свій ендпоінт
Section titled “1. Зареєструйте свій ендпоінт”curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'Використовуйте власну публічну HTTPS-адресу. Локальні та приватні адреси відхиляються. Збережіть secret, повернутий під час створення ендпоінту: він потрібен для перевірки запитів.
У магазину може бути до 10 ендпоінтів. URL ендпоінту можна змінити, тож використовуйте наявний замість додавання нового. Див. Ліміти.
2. Оберіть потрібні події
Section titled “2. Оберіть потрібні події”| Подія | Значення |
|---|---|
transfer.observed |
Переказ помічено; він ще не підтверджений. |
transfer.confirmed |
Вхідний переказ має достатньо підтверджень. Це може бути лише частковий платіж за рахунком. |
transfer.reverted |
Попередню подію переказу відкотили. |
invoice.closed |
Рахунок закрився в мережі. |
invoice.cancelled |
Сторінку оплати скасовано або в рахунку минув термін; це не повернення коштів. |
payout.sent |
Виплату розіслано в мережу або помічено її вихідний переказ. |
payout.confirmed |
Доступний повний облік розрахунку. |
payout.reverted |
Попереднє підтвердження виплати відкотили. |
payout.failed |
Остаточна невдача виплати потребує втручання. |
Для invoice.cancelled data.reason пояснює причину: expired, коли скінчився термін дії рахунку, merchant_blocked, коли персонал Invoise заблокував мерчанта. Скасування мерчантом, зокрема через архівування магазину, не має reason.
Порожній список filters отримує всі події. Інакше перелічіть групи (transfer, invoice, payout), окремі типи подій, як-от payout.confirmed, або й те, й інше. Вхідні перекази та вихідні виплати — різні події. Тимчасова затримка RPC чи газу — це не payout.failed.
gas.wait і sweep.failed приймаються як фільтри, але Invoise не надсилає їх на ваш ендпоінт. Це внутрішні сигнали: gas.wait означає, що виплата очікує кошти на мережеву комісію й продовжується сама; sweep.failed означає, що спроба перемістити кошти вашому отримувачу не вдалася. Для жодного з них дія не потрібна. Виплата, яка не може завершитися, доходить до вас як payout.failed.
У магазині-пісочниці можна симулювати обидва через POST /shops/{shop_id}/sandbox/simulate, щоб перевірити, що затримана виплата не ламає ваш процес. Вони змінюють лише стан виплати й не надсилають вебхук.
3. Перевірте перед обробкою
Section titled “3. Перевірте перед обробкою”Invoise-Signature має форму t=<timestamp>,v1=<hex>. Підпис — це HMAC-SHA256 від timestamp + "." + raw_body, з використанням вашого секрету вебхука.
Наступний приклад на Node.js також відхиляє часові мітки, що відрізняються від годинника сервера більш ніж на п’ять хвилин. Тримайте цей годинник синхронізованим і свідомо обирайте свій допуск.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) { const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? ''); if (!match) return false; const [, timestamp, signature] = match; const age = Math.abs(Date.now() / 1000 - Number(timestamp)); if (!Number.isFinite(age) || age > 300) return false; const expected = createHmac('sha256', secret) .update(timestamp + '.') .update(rawBody) .digest(); return timingSafeEqual(Buffer.from(signature, 'hex'), expected);}Передавайте оригінальні байти запиту як rawBody. Не розбирайте JSON і не перетворюйте його назад у рядок перед перевіркою підпису. Відхиляйте неправильні підписи до збереження чи дії за їхнім вмістом.
4. Обробляйте один раз
Section titled “4. Обробляйте один раз”Так виглядає тіло transfer.confirmed. Схема кожної події — у розділі webhooks файлу openapi.json.
{ "id": "<event-id>", "type": "transfer.confirmed", "created_at": "2026-09-19T10:00:05Z", "data": { "issuance_id": "<issuance-id>", "public_id": "<public-id>", "shop_id": "<shop-id>", "external_id": "customer-42", "type": "deposit", "family": "evm", "chain_id": 8453, "token": "<token-address>", "token_decimals": 6, "address": "<payment-address>", "recipient": "<recipient-address>", "invoice_cancelled": false, "cancelled_at": null, "direction": "incoming", "chain_event": { "event_id": "<transfer-id>", "kind": "transfer.confirmed", "chain_id": 8453, "tx_hash": "<tx-hash>", "log_index": 2, "block_number": 35123456, "block_hash": "<block-hash>", "token": "<token-address>", "from": "<payer-address>", "to": "<payment-address>", "amount": "25000000", "confirmations": 12, "occurred_at": "2026-09-19T10:00:00Z" } }}Щоб зарахувати платіж, читайте data.chain_event. amount — скільки надійшло, у базових одиницях токена: поділіть на 10^data.token_decimals, тобто 25000000 при 6 знаках — це 25 токенів. event_id — ID переказу, tx_hash — його транзакція. data.issuance_id і data.external_id показують, який рахунок чи депозит він оплатив. Для рахунку один переказ може бути частковою оплатою.
| Випадок | Обробка |
|---|---|
| Дублікати | Усувайте дублікати за Invoise-Event-ID, який збігається з id конверта. Зберігайте ID і бізнес-оновлення атомарно. |
| Прийняття події | Зберігайте прийняті події надійно, повертайте 2xx одразу, а чергу обробляйте потім. |
| Повтори й відтворення | Повтори й ручні відтворення повторюють той самий ID події. Invoise-Attempt-ID змінюється і не є ключем усунення дублікатів. |
| Заголовки | Кожен запит містить Invoise-Event-ID і Idempotency-Key, обидва дорівнюють id події; Invoise-Delivery-ID, один на подію й ендпоінт; Invoise-Attempt-ID, новий для кожної спроби; та Invoise-Signature. |
| Порядок подій | Події можуть надходити не по порядку. Використовуйте їхній вміст і за потреби звіряйте з поточним статусом. |
Якщо реорганізація мережі скасувала переказ, надійде transfer.reverted, де chain_event.reference_event_id дорівнює event_id зарахованого переказу: спишіть цю суму. У payout.confirmed є amount — скільки отримав одержувач — і service_fee — комісія з цієї виплати; у payout.sent і payout.failed обидва поля null. Кожна подія виплати має стабільний payout_id і хеш транзакції. incoming_transfer_ids перелічує перекази, що увійшли у виплату, не більше 100; incoming_transfers_truncated позначає, що список довший.
Старіші збережені події можуть використовувати project_id; спершу читайте shop_id, а за потреби повертайтеся до нього. Відтворення зберігають оригінальні байти.
Звірка з журналом
Section titled “Звірка з журналом”GET /api/v1/shops/{shop_id}/deposits — повний журнал підтверджених вхідних переказів магазину, і за рахунками, і за депозитами, від нових до старих. Це не список адрес: POST на той самий шлях створює депозитну адресу. Кожен рядок має id, що дорівнює chain_event.event_id з вебхука, а також issuance_id, external_id, amount, tx_hash, sender і occurred_at. Гортайте його через limit і cursor, щоб надолужити пропущене після простою або звірити свої записи.
status у журналі завжди confirmed. Переказ, скасований реорганізацією, зникає з журналу, а вам надходить transfer.reverted.
Повтори
Section titled “Повтори”Доставка успішна, коли ваш ендпоінт відповідає будь-яким статусом 2xx. Інший статус, таймаут або помилка з’єднання повторюються: перший повтор — через 5 секунд, далі пауза подвоюється після кожної спроби, але не перевищує години. Якщо за 72 години відповіді 2xx так і не було, Invoise припиняє спроби й позначає доставку як failed.
На кожну спробу відведено 20 секунд, а заголовки відповіді мають надійти протягом 10 секунд. Спершу збережіть подію й відповідайте, а обробляйте потім.
Архівовані магазини
Section titled “Архівовані магазини”Архівування магазину через PATCH /api/v1/shops/{shop_id} з {"archived":true} вимикає його вебхуки. Події магазину, зокрема invoice.cancelled для його неоплачених рахунків, і далі записуються, але не доставляються.
Перегляд невдалої доставки
Section titled “Перегляд невдалої доставки”Список: GET /api/v1/shops/{shop_id}/deliveries. Повторіть доставку через POST /api/v1/shops/{shop_id}/deliveries/{id}/replay зі збереженим ключем ідемпотентності. Повтор не створює нову бізнес-подію. Він відкриває нове 72-годинне вікно повторів; повторити можна і доставлену, і невдалу доставку.