Приймання й виплати через один узгоджений контракт

Огляд

Кожен запит підписується й іде на версійований шлях /api/v1/…. Версія живе у шляху: коли зʼявиться v2, ваша інтеграція на v1 продовжить працювати без змін. Усередині версії ми лише додаємо поля — ніколи не прибираємо й не перейменовуємо.

Автентифікація & підпис

До кожного запиту додайте два заголовки. Порядок перевірки на сервері: ліміт частоти → цілісність тіла → ключ → підпис, тож помилка називає саме свою причину.

Підписується точні байти тіла, які ви відправляєте — серіалізуйте JSON один раз і підпишіть саме цей рядок. У GET-запитів тіло порожнє, тож X-Signature — це HMAC порожнього рядка з api_secret.

# тіло, яке відправляємо
BODY='{"order_id":"A-1001","amount":1500.00,"currency":"UAH"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

curl -X POST https://lumapay.org/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

Додатково: якщо у профілі задано білий список IP, запити приймаються лише з нього (перевіряється REMOTE_ADDR, X-Forwarded-For ігнорується).

Ідемпотентність

Заявки й виплати ідемпотентні за парою (мерчант, order_id). Точний повтор того самого запиту повертає оригінальний обʼєкт (не створює дубль). Той самий order_id зі зміненим тілом (сума, валюта, платник / картка отримувача) — це конфлікт 409 idempotency_conflict, у відповіді буде наявний обʼєкт.

Заявки на приймання

Створює заявку payin і повертає реквізит (картку), який показуєте платнику. Комісія утримується з суми (inclusive): мерчанту зараховується amount − commission.

{
  "order_id": "A-1001",
  "amount": 1500.00,
  "currency": "UAH",
  "payer_id": "user-42"
}

{
  "id": "7af7c1df-0629-42d4-9068-df6500b3acd6",
  "order_id": "A-1001",
  "status": "awaiting_payment",
  "amount": 1500.00,
  "amount_settled": null,
  "commission": 30.00,
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "payer_id": "user-42",
  "requisite": {
    "card_number": "5375 4141 0000 1234",
    "card_holder": "ПЕТРЕНКО ІВАН",
    "bank": "PrivatBank",
    "type": "card"
  },
  "created_at": "2026-08-09T10:00:00+00:00",
  "expires_at": "2026-08-09T10:15:00+00:00",
  "completed_at": null
}

Показуйте requisite.card_number платнику; чекайте на вебхук order.completed (не поллінг). Поле id — це {uuid} для запиту статусу.

При "method": "iban" у requisite: type = iban, card_number = null, iban (UA…, 29 знаків), card_holder - найменування/ПІБ отримувача, bank_code - ЄДРПОУ/МФО/РНОКПП, payment_purpose - призначення платежу або null. Вільного IBAN немає - 503 no_requisite_available, як і для картки.

При "method": "quasi" у requisite: type = quasi, pay_link - посилання, за яким платить платник, card_number і card_holder = null. Метод працює лише на поповнення і лише з підключеним тарифом: без нього - 422 method_not_enabled.

Якщо для методу підключено готову сторінку оплати, у відповіді є payment_url - посилання, на яке можна одразу перенаправити платника: реквізити, таймер і кнопку «Я оплатив» показує сторінка. Поля немає - показуйте requisite у себе. Необовʼязковий return_url у запиті (http/https, до 255 знаків) - адреса кнопки повернення на ваш сайт.

Повертає поточний стан заявки (той самий обʼєкт, що й POST /orders). Заявка іншого мерчанта невидима навіть за відомим UUID.

Якщо за заявкою є спір, у відповіді є поле dispute - той самий обʼєкт, що повертає POST /orders/{uuid}/dispute, за останнім спором заявки. Немає спору - немає й поля.

Зняти заявку, яку ще не оплатили: платник передумав або оператор закриває її з вашого боку. Картка трейдера одразу звільняється під наступну заявку. У відповідь приходить той самий обʼєкт заявки зі статусом cancelled, і на ваш callback_url іде подія order.cancelled.

Тіло не обовʼязкове. Можна передати reason — причина потрапить у вебхук, у журнал і в картку заявки, де її бачить оператор платіжної системи, тож пишіть зрозумілий текст, а не службовий код; порожнє тіло {} теж приймається, тоді запишеться «Cancelled by merchant». Підписуйте рівно той рядок, який надсилаєте.

Скасувати можна лише неоплачену заявку — статуси pending і awaiting_payment. Щойно платник переказав гроші (processing) або відкрито спір, скасування через API вже не працює: кошти могли надійти на картку трейдера, і такий випадок закриває підтримка. Відповідь — 409 order_not_cancellable і поточний стан заявки в полі order.

Лише для заявок з method=iban і method=quasi. Платник зробив переказ і натиснув «Я оплатив» у вашій формі: передайте його квитанцію, ми покажемо її трейдеру. Для quasi квитанція не обовʼязкова: запит приймається і без receipts, далі платіж підтверджує трейдер. Заявка переходить у processing і чекає підтвердження трейдера; таймер expires_at для неї більше не діє. Результат прийде звичайним вебхуком order.completed або order.disputed.

{"receipts": ["iVBORw0KGgoAAAANSUhEUgAA..."]}

Повторний виклик додає квитанції до вже переданих, разом не більше 3 на заявку. У відповідь - обʼєкт заявки з полями payer_paid_at і receipts_count.

Помилки: 422 method_not_supported - заявка не IBAN і не quasi; 422 receipt_invalid, receipt_type_not_supported, receipt_too_large, receipt_limit - файл не прийнято; 409 order_not_active - заявка вже закрита, протермінована або в спорі (поточний стан у полі order).

Платник заплатив, а заявку не зараховано: протермінувалась, зарахована на меншу суму або ще в роботі. Передайте його квитанцію - відкриється спір, як через Telegram-бота чи кабінет. Працює для заявок будь-якого методу і статусу. Замість нашого uuid у шляху можна передати ваш order_id.

Далі спір іде до трейдера. Підтвердив - заявку зараховано автоматично або після перевірки підтримкою; гроші приходять звичайним вебхуком order.completed або order.amount_corrected. Рішення по спору - вебхук dispute.resolved.

{"receipts": ["JVBERi0xLjQK..."], "comment": "Оплатив 1500 о 14:05, заявка протермінувалась"}

Відповідь - 201, якщо спір відкрито, і 200, якщо за заявкою вже є відкритий спір: тоді нові квитанції додаються до нього. Ту саму квитанцію вдруге не додаємо, тож запит можна безпечно повторити після таймауту; якщо спір уже вирішено, повтор з тими самими квитанціями поверне його ж (200), а з новою квитанцією відкриє новий спір.

{
  "dispute": {
    "id": 731,
    "number": "100731",
    "status": "open",
    "outcome": null,
    "created_at": "2026-10-18T14:20:11+00:00",
    "resolved_at": null,
    "already_credited": false
  },
  "order": { ... }
}

Помилки: 422 receipt_invalid, receipt_type_not_supported, receipt_too_large, receipt_limit - файл не прийнято; 409 dispute_not_available - тестова заявка пісочниці.

Виплати

Створює виплату на картку або на IBAN отримувача. Комісія додається зверху (on-top): з мерчанта списується amount + commission = amount_charged.

{
  "id": "b1e2c3d4-5678-90ab-cdef-1234567890ab",
  "order_id": "P-2001",
  "status": "pending",
  "amount": 1000.00,
  "commission": 15.00,
  "amount_charged": 1015.00,
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "method": "card",
  "recipient": { "card_number": "4149 •••• •••• 3179", "name": "IVAN P.", "bank": "A-Bank" },
  "receipt_attached": false,
  "receipts": [],
  "created_at": "2026-08-09T10:00:00+00:00",
  "expires_at": "2026-08-09T14:00:00+00:00",
  "completed_at": null
}

Для method=iban у відповіді method: "iban", у recipient - iban (замаскований), tax_id і payment_purpose, а card_number - null. Комісія - ставка виплати на IBAN з вашого тарифу; якщо окремої ставки немає, як виплата на картку. Реквізити IBAN, ЄДРПОУ/ІПН і призначення беруть участь в ідемпотентності.

Стан виплати (той самий обʼєкт, що й при створенні), scoped до вашого мерчанта.

Файл чека виплати, тип файлу - у заголовку Content-Type. Готові посилання лежать у полі receipts обʼєкта виплати та вебхука: чеків буває до 5, {index} - номер із посилання. Запит підписується як будь-який GET: X-API-Key і X-Signature від порожнього тіла. Чеки доступні у статусах processing, completed і disputed.

Помилки: 404 payout_not_found - виплати немає або вона не ваша; 404 receipt_not_found - чека з таким номером немає.

Відкликати виплату, поки її ніхто не взяв. Тіло порожнє — надішліть {} і підпишіть саме ці два байти. У відповідь приходить той самий обʼєкт виплати зі статусом cancelled, і на ваш callback_url іде подія payout.cancelled.

Щойно виплату взяв трейдер, скасувати її через API вже не можна: він міг почати переказ. Такий випадок закриває підтримка — відповідь 409 payout_not_cancellable і поточний стан виплати в полі payout.

Баланс

Баланс і оборот у розрізі валют, рахуються так само, як у кабінеті: зараховано − видано − холд під незавершені виплати − заявки на вивід + правки (заявки — у резервуючих статусах; правки — ручні корекції адміністратора, поле adjustments).

{
  "merchant_id": 1,
  "balances": [
    {
      "currency": "UAH",
      "balance": 598229.84,
      "settled": 6449109.84,
      "paid_out": 5849865.00,
      "held": 1015.00,
      "withdrawn": 0.00,
      "adjustments": 0.00,
      "turnover": 7010100.00,
      "commission": 560792.16,
      "orders": 438,
      "payouts": 56,
      "withdrawals": 0
    }
  ],
  "generated_at": "2026-08-09T10:15:00+00:00"
}

Вебхуки

Ми надсилаємо POST на вашу адресу доставки на ключові переходи — завершення й прострочення заявки, корекцію суми, і зміни виплат — а не буквально на кожну зміну статусу. Відповідайте 2xx швидко; тіло обробляйте ідемпотентно.

Події заявок

Канонічний payload однаковий для всіх подій order.*: незмінний порядок і назви полів.

Ручний повтор із адмінки надсилає той самий payload із додатковим прапорцем "resent": true.

{
  "event": "order.completed",
  "order_id": "7af7c1df-0629-42d4-9068-df6500b3acd6", // наш uuid
  "merchant_order_id": "A-1001",                      // ваш номер
  "status": "completed",
  "currency": "UAH",
  "amount": 1500.00,                                  // до оплати (не змінюється)
  "amount_requested": 1500.00,                        // яку ви запросили
  "amount_received": 1500.00,                         // фактично отримана
  "amount_settled": 1470.00,                          // до зарахування (мінус комісія)
  "exchange_rate": 45.58,
  "settlement_currency": "USDT"
}

{
  "event": "order.amount_corrected",
  "order_id": "7af7c1df-0629-42d4-9068-df6500b3acd6",
  "merchant_order_id": "A-1001",
  "status": "completed",
  "currency": "UAH",
  "amount": 1500.00,
  "amount_received": 1400.00,
  "amount_settled": 1372.00,
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "correction_id": 42,
  "reason": "partial_payment",
  "amount_original": 1500.00, // сума до корекції
  "amount_corrected": 1400.00 // нова сума
}

Події виплат

{
  "event": "payout.completed",
  "payout_id": "b1e2c3d4-5678-90ab-cdef-1234567890ab", // наш uuid
  "order_id": "P-2001",                                // ВАШ зовнішній номер
  "amount": 1000.00,
  "amount_charged": 1015.00,                           // списано з мерчанта
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "status": "completed",
  "tx_receipt": "https://.../api/v1/payouts/b1e2c3d4-5678-90ab-cdef-1234567890ab/receipts/0", // перший чек
  "receipts": ["https://.../api/v1/payouts/b1e2c3d4-5678-90ab-cdef-1234567890ab/receipts/0"],
  "completed_at": "2026-08-09T10:15:00+00:00"
}

Доставка & ретраї

Доставка асинхронна через чергу. Успіх — будь-який 2xx. Не-2xx або таймаут (connect 5с / read 15с) плануює повтор із наростаючою затримкою.

До 5 спроб; після вичерпання колбек позначається failed. Обробляйте ідемпотентно за order_id/payout_id — той самий колбек може прийти повторно.

Коди помилок

Усі помилки — JSON із полем error (машинний код) і message. Робіть switch по error, не по тексту.