Accept and pay out through one consistent contract

Overview

Every request is signed and goes to a versioned path /api/v1/…. The version lives in the path: when v2 arrives, your v1 integration keeps working unchanged. Within a version we only add fields — we never remove or rename them.

Authentication & signature

Add two headers to every request. The server's verification order is: rate limit → body integrity → key → signature, so the error names its exact cause.

The exact bytes of the body you send are signed — serialize the JSON once and sign that very string. For GET requests the body is empty, so X-Signature is the HMAC of an empty string with api_secret.

# the body we send
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"

Additionally: if an IP allowlist is set in the profile, requests are accepted only from it (REMOTE_ADDR is checked, X-Forwarded-For is ignored).

Idempotency

Orders and payouts are idempotent by the pair (merchant, order_id). An exact repeat of the same request returns the original object (no duplicate is created). The same order_id with a changed body (amount, currency, payer / recipient card) is a 409 idempotency_conflict conflict, and the response contains the existing object.

Payin orders

Creates a payin order and returns the requisite (card) you show to the payer. The commission is withheld from the amount (inclusive): the merchant is credited 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": "IVAN PETRENKO",
    "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
}

Show requisite.card_number to the payer; wait for the order.completed webhook (not polling). The id field is the {uuid} for the status request.

With "method": "iban" the requisite has type = iban, card_number = null, iban (UA…, 29 chars), card_holder - recipient name, bank_code - EDRPOU/MFO/RNOKPP, payment_purpose - payment reference or null. No free IBAN - 503 no_requisite_available, same as for cards.

With "method": "quasi" the requisite has type = quasi, pay_link - the link the payer pays through, and card_number and card_holder = null. The method is pay-in only and needs an enabled tariff: without it - 422 method_not_enabled.

If a hosted payment page is enabled for the method, the response contains payment_url - a link you can redirect the payer to right away: the page shows the details, the timer and the "I have paid" button. If the field is absent, show requisite on your side. The optional return_url in the request (http/https, up to 255 characters) is the address of the button that returns the payer to your site.

Returns the current state of the order (the same object as POST /orders). Another merchant's order is invisible even with a known UUID.

If the order has a dispute, the response carries a dispute field - the same object POST /orders/{uuid}/dispute returns, for the latest dispute of the order. No dispute - no field.

Cancel an order that has not been paid yet: the payer changed their mind, or an operator closes it on your side. The trader card is freed for the next order immediately. The response carries the same order object with status cancelled, and an order.cancelled event is sent to your callback_url.

The body is optional. You may pass reason — it goes into the webhook, the audit log and the order card, where a payment-system operator reads it, so write a human-readable text rather than an internal code; an empty body {} is accepted too, and «Cancelled by merchant» is recorded. Sign exactly the string you send.

Only unpaid orders can be cancelled — statuses pending and awaiting_payment. Once the payer has sent the money (processing) or a dispute is open, API cancellation no longer works: funds may already have reached the trader card, and support handles such cases. The response is 409 order_not_cancellable with the current order state in the order field.

For method=iban and method=quasi orders only. The payer made the transfer and pressed "I have paid" in your form: send us the receipt and we show it to the trader. For quasi the receipt is optional: the request is accepted without receipts, then the trader confirms the payment. The order moves to processing and waits for the trader to confirm; the expires_at timer no longer applies. The outcome arrives as the usual order.completed or order.disputed webhook.

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

A repeated call adds receipts to those already sent, at most 3 per order in total. The response is the order object with payer_paid_at and receipts_count.

Errors: 422 method_not_supported - neither an IBAN nor a quasi order; 422 receipt_invalid, receipt_type_not_supported, receipt_too_large, receipt_limit - file rejected; 409 order_not_active - the order is already closed, expired or under dispute (current state in the order field).

The payer paid, but the order was not credited: it expired, was credited for a smaller amount or is still in progress. Send the payer's receipt and a dispute is opened, the same as through the Telegram bot or the cabinet. Works for orders of any method and status. Instead of our uuid the path may carry your order_id.

The dispute then goes to the trader. Once confirmed, the order is credited automatically or after a support check; the money arrives as the usual order.completed or order.amount_corrected webhook. The dispute decision is the dispute.resolved webhook.

{"receipts": ["JVBERi0xLjQK..."], "comment": "Paid 1500 at 14:05, the order expired"}

The response is 201 when a dispute is opened and 200 when the order already has an open dispute: new receipts are added to it. The same receipt is never added twice, so the request is safe to retry after a timeout; once the dispute is resolved, a retry with the same receipts returns it (200), while a new receipt opens a new dispute.

{
  "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": { ... }
}

Errors: 422 receipt_invalid, receipt_type_not_supported, receipt_too_large, receipt_limit - file rejected; 409 dispute_not_available - a sandbox test order.

Payouts

Creates a payout to the recipient's card or IBAN. The commission is added on top (on-top): the merchant is charged 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
}

For method=iban the response has method: "iban", and recipient contains iban (masked), tax_id and payment_purpose, while card_number is null. The commission is the IBAN payout rate from your tariff; if no separate rate is set, the card payout rate applies. IBAN, tax number and purpose participate in idempotency.

Payout state (the same object as at creation), scoped to your merchant.

The payout receipt file, its type is in the Content-Type header. Ready links are in the receipts field of the payout object and of the webhook: a payout can have up to 5 receipts, {index} is the number from the link. Sign the request like any GET: X-API-Key and X-Signature of the empty body. Receipts are available in the processing, completed and disputed statuses.

Errors: 404 payout_not_found - no such payout or it is not yours; 404 receipt_not_found - no receipt with this index.

Withdraw a payout while no trader has taken it. The body is empty — send {} and sign exactly those two bytes. The response is the same payout object with status cancelled, and a payout.cancelled event goes to your callback_url.

Once a trader has taken the payout, the API will not cancel it: the transfer may already be under way. Support closes such cases — the answer is 409 payout_not_cancellable with the current payout state in the payout field.

Balance

Balance and turnover broken down by currency, computed the same way as in the dashboard: settled − paid out − hold on open payouts − withdrawal requests + adjustments (requests in reserving statuses; adjustments are manual corrections made by an administrator, the adjustments field).

{
  "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"
}

Webhooks

We send a POST to your delivery address on key transitions — order completion and expiry, amount correction, and payout changes — rather than literally on every status change. Respond with 2xx quickly; process the body idempotently.

Order events

The canonical payload is the same for all order.* events: fixed field order and names.

A manual resend from the admin panel sends the same payload with an extra flag "resent": true.

{
  "event": "order.completed",
  "order_id": "7af7c1df-0629-42d4-9068-df6500b3acd6", // our uuid
  "merchant_order_id": "A-1001",                      // your number
  "status": "completed",
  "currency": "UAH",
  "amount": 1500.00,                                  // to pay (does not change)
  "amount_requested": 1500.00,                        // what you requested
  "amount_received": 1500.00,                         // actually received
  "amount_settled": 1470.00,                          // to be credited (minus commission)
  "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 before correction
  "amount_corrected": 1400.00 // new amount
}

Payout events

{
  "event": "payout.completed",
  "payout_id": "b1e2c3d4-5678-90ab-cdef-1234567890ab", // our uuid
  "order_id": "P-2001",                                // YOUR external number
  "amount": 1000.00,
  "amount_charged": 1015.00,                           // charged to the merchant
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "status": "completed",
  "tx_receipt": "https://.../api/v1/payouts/b1e2c3d4-5678-90ab-cdef-1234567890ab/receipts/0", // first receipt
  "receipts": ["https://.../api/v1/payouts/b1e2c3d4-5678-90ab-cdef-1234567890ab/receipts/0"],
  "completed_at": "2026-08-09T10:15:00+00:00"
}

Delivery & retries

Delivery is asynchronous via a queue. Success is any 2xx. A non-2xx or timeout (connect 5s / read 15s) schedules a retry with increasing delay.

Up to 5 attempts; after they are exhausted the callback is marked failed. Process idempotently by order_id/payout_id — the same callback may arrive again.

Error codes

All errors are JSON with an error field (machine code) and message. Switch on error, not on the text.