Депозити та рахунки

Використовуйте рахунок для одного замовлення з фіксованою ціною. Використовуйте депозит для балансу клієнта, який можна поповнювати багаторазово.

Створіть рахунок

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 пов’язує рахунок із замовленням у вашій системі; він не замінює ключ ідемпотентності.

Відповідь — 202 Accepted. Збережіть її id і опитуйте ендпоінт рахунку, поки не з’явиться address. Потім передайте платнику отриманий payment_url.

Часткові платежі підсумовуються. Щойно надходить достатньо підтверджених коштів, Invoise планує виплату й закриває рахунок. Отримувач отримує суму рахунку за вирахуванням комісії сервісу. Будь-яка переплата йде в Invoise, а не отримувачу.

Рахунки — це одноразові платежі; вони не поновлюються автоматично.

Термін дії рахунку

За замовчуванням рахунок залишається відкритим 30 днів. Щоб обрати інший термін, додайте expires_in до тіла запиту, наприклад "expires_in":"7d". Допустимі значення: 1d, 7d, 30d, 180d і 365d.

Відповіді з рахунком, зокрема публічна сторінка оплати, містять expires_at. Коли цей час минає, неоплачений рахунок закривається: встановлюється cancelled_at, а вебхук invoice.cancelled надсилається з data.reason, установленим у expired. Платіж, що надійшов пізніше, все одно записується й може розрахуватися — як і у випадку скасованого рахунку.

Депозити не мають терміну дії. Надсилання expires_in під час створення депозиту повертає 400 invalid_expires_in.

Створіть депозитну адресу

Використовуйте ті самі заголовки запиту з цим ендпоінтом і тілом:

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.

Запропонуйте кілька токенів або мереж

Надішліть 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": "registering",
  "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": null,
      "status": "registering"
    }
  ],
  "expires_at": "2026-10-19T09:00:00Z"
}

Збережіть id групи. GET /api/v1/shops/{shop_id}/issuances/{id} повертає групу з усіма варіантами; опитуйте його, поки варіанти не отримають адреси, потім передайте платнику payment_url групи, де він обере варіант.

Групу рахунку оплачують один раз. Її 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.

Ліміти

Один рахунок може бути щонайбільше 1 000 000 токенів. У мерчанта може бути до 2000 активних рахунків і обмежена кількість активних депозитних адрес на родину мереж. Скасовуйте непотрібні рахунки або вимикайте непотрібні депозити, щоб звільнити місце. Точні значення й коди помилок див. у Лімітах.

Призупиніть депозит або скасуйте рахунок

Дія	Запит
Призупинити сторінку оплати депозиту	`PATCH /api/v1/shops/{shop_id}/deposits/{id}` з `{"enabled":false}`. Використайте `true`, щоб увімкнути знову.
Скасувати сторінку оплати рахунку	`POST /api/v1/shops/{shop_id}/invoices/{id}/cancel`.

Надсилайте автентифікацію і збережений Idempotency-Key для будь-якої з операцій.

Ці дії закривають сторінку оплати. Вони не повертають гроші й не зупиняють відстеження адреси. Кошти, надіслані на скасований рахунок, усе одно можуть розрахуватися; його події містять invoice_cancelled: true.

Кошти, надіслані після того, як рахунок уже розрахувався, записуються як пізні перекази. Вони не виплачуються автоматично. Повернення, зокрема повернення не того токена, вимагає окремої ручної операції.

Повний перелік полів запиту й відповіді див. у довіднику API.