Депозити та рахунки
Використовуйте рахунок для одного замовлення з фіксованою ціною. Використовуйте депозит для балансу клієнта, який можна поповнювати багаторазово.
Створіть рахунок
Section titled “Створіть рахунок”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, а не отримувачу.
Рахунки — це одноразові платежі; вони не поновлюються автоматично.
Термін дії рахунку
Section titled “Термін дії рахунку”За замовчуванням рахунок залишається відкритим 30 днів. Invoise може змінити цей термін, тож надсилайте expires_in, якщо ваша інтеграція від нього залежить. Щоб обрати інший термін, додайте expires_in до тіла запиту, наприклад "expires_in":"7d". Допустимі значення: 1h, 2h, 1d, 7d, 30d, 180d і 365d.
Відповіді з рахунком, зокрема публічна сторінка оплати, містять expires_at. Коли цей час минає, неоплачений рахунок закривається: встановлюється cancelled_at, а вебхук invoice.cancelled надсилається з data.reason, установленим у expired. Платіж, що надійшов пізніше, все одно записується й може розрахуватися — як і у випадку скасованого рахунку. Для короткого терміну, як-от 1h, 2h чи 1d, підпишіться на invoice.cancelled, щоб одразу дізнаватися про завершення терміну.
Депозити не мають терміну дії. Надсилання expires_in під час створення депозиту повертає 400 invalid_expires_in.
Створіть депозитну адресу
Section titled “Створіть депозитну адресу”Використовуйте ті самі заголовки запиту з цим ендпоінтом і тілом:
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. Комісія береться з кожної виплати, а не з кожного вхідного переказу: поповнення, виплачені разом, сплачують одну комісію, і мінімальна комісія мережі застосовується один раз на виплату. Рахунок сплачує комісію один раз, із суми рахунку.
Запропонуйте кілька токенів або мереж
Section titled “Запропонуйте кілька токенів або мереж”Надішліть 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.
Ліміти
Section titled “Ліміти”За замовчуванням один рахунок може бути щонайбільше 1 000 000 токенів. У мерчанта може бути до 2000 активних рахунків і до 100 000 активних депозитних адрес у мережах EVM, 100 000 у Tron і 100 у Solana, а нових адрес для оплати за годину він може створити не більше, ніж його ліміт активних рахунків. Скасовуйте непотрібні рахунки або вимикайте непотрібні депозити, щоб звільнити місце. Це значення за замовчуванням: персонал Invoise може встановити мерчанту інші ліміти. Щоб обслуговувати більше платників, вимикайте депозити, що простоюють, і вмикайте їх знову, коли вони знадобляться: вимкнений депозит не займає місця в ліміті, а для повторного ввімкнення потрібне вільне місце. Вимкнена адреса й далі відстежується, тож гроші, що надійдуть на неї пізніше, усе одно зараховуються й виплачуються. Вимкнена адреса Solana, на яку годину нічого не надходило, перевіряється раз на годину, тож такі гроші видно із затримкою до години; не вимикайте адресу, на яку ще чекаєте оплату. Які адреси перемикати, вирішуєте ви; перемикати може й API-ключ магазину з правом write. Точні значення й коди помилок див. у Лімітах.
Призупиніть депозит або скасуйте рахунок
Section titled “Призупиніть депозит або скасуйте рахунок”| Дія | Запит |
|---|---|
| Призупинити сторінку оплати депозиту | 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.