Приём и выплаты через один согласованный контракт

Обзор

Каждый запрос подписывается и идёт на версионированный путь /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, не по тексту.