Payment Orchestrator
Payment Orchestrator is a single API for accepting and managing payments across multiple payment providers. You integrate once; Lunixi routes every transaction to the optimal provider, handles 3D Secure, retries recoverable failures on an alternative provider, and reports every state change back to you through a consistent status model and webhooks.
All amounts across the API are integers in minor units (kuruş). "amount": 10050 means ₺100.50. There are no decimal amounts anywhere.
Three product lines
The Payment Orchestrator tab covers three product lines that share the same platform, the same authentication model and the same webhook delivery:
| Line | What it does | Start here |
|---|---|---|
| Payments | Accept one-off card payments — hosted checkout form, direct API or a shareable payment link, 3D Secure, installments, capture/void/refund, disputes | Quickstart · Payment Links |
| Marketplace | Split a single charge across sub-sellers, onboard sellers, manage commissions and payouts | Marketplace overview |
| Subscription | Recurring billing — products, plans, invoices, saved cards, usage metering and a hosted customer portal | Subscription overview |
Running a wallet under your own brand — top-ups, wallet-to-wallet transfers, wallet payments, QR and loyalty — is a separate product: Wallet. To refund a card payment into a wallet instead of the card, see Refund to Wallet.
Two ways to accept a payment
| Hosted checkout | Direct API | |
|---|---|---|
| Card data | Entered on Lunixi's checkout form — card data never touches your server | Sent server-to-server from your backend |
| You call | POST /payments/intents, then mount the form with the returned token | POST /payments/direct/payment (Payment) |
| PCI scope | Minimal — Lunixi handles the card | Full — requires PCI DSS compliance on your side |
| Best for | The fastest, lowest-compliance integration | Full control over the payment UX |
Both paths share the same provider routing, failover, 3D Secure handling, installment logic and webhooks. Most integrations should start with the hosted checkout — see the Checkout Form page for the complete reference.
To take payments without a checkout form on your site, use Payment Links: you create a link through the API and the buyer pays on pay.lunixi.com with the same Lunixi payment form.
Multi-provider routing & failover
You can connect more than one payment provider (and more than one credential per provider) to your account. For each transaction, Lunixi's smart routing selects the optimal provider for that specific payment — taking live provider health, historical performance and cost into account — with no routing code on your side.
When a payment fails, the failure is classified first:
- Retryable failures (provider outage, network timeout, rate limiting) are automatically re-routed to the next eligible provider — the buyer usually never notices.
- Non-retryable declines (insufficient funds, invalid card, failed 3D Secure) are returned as final. Re-trying these on another provider would waste the buyer's time and can trigger fraud flags, so the orchestrator never does it.
Follow-up operations — capture, void, refund — always settle against the original provider and credential that processed the payment. They are never re-routed.
Payment lifecycle
Every payment moves through an explicit status. These are the exact values you will see on GET /payments/:id and in webhook payloads:
CAPTURED, not at AUTHORIZED — an authorization only places a hold. Terminal and exceptional states (FAILED, EXPIRED, CHARGEDBACK, NEEDS_RECONCILIATION) are in the table below.| Status | Meaning |
|---|---|
INITIATED | Intent created, no charge attempt yet |
PROCESSING | A charge attempt is in flight |
AWAITING_3D | Buyer redirected to the 3D Secure challenge |
AUTHORIZED | Funds reserved, not yet captured |
CAPTURED / PARTIALLY_CAPTURED | Funds captured (fully or partially) |
SETTLED | Funds settled by the provider |
REFUNDED / PARTIALLY_REFUNDED | Refund issued (fully or partially) |
VOIDED | Authorization released before capture |
FAILED | Final decline |
EXPIRED | Abandoned checkout or 3D Secure session swept automatically |
CHARGEDBACK | A dispute was opened — see Chargebacks |
NEEDS_RECONCILIATION | Outcome uncertain; parked for investigation instead of being silently failed |
Security model
- Read endpoints (listing, payment detail, BIN lookups) use a server-side Bearer access token (
at_live_…). - Money movement endpoints (creating intents, direct charges, capture/void/refund) require Step-Up auth: the Bearer key plus an Ed25519 request signature.
- The buyer side of the hosted form authenticates with a short-lived form token and a session-proof cookie — your secret key never reaches the browser.
- Every payment POST accepts an
Idempotency-Keyheader so a network retry can never charge twice.
The full model, with signing examples, is on the Authentication page.
Webhooks
Payment state changes are pushed to your endpoint as signed webhook events:
payment.authorized · payment.captured · payment.partially_captured · payment.failed · payment.refunded · payment.partially_refunded · payment.voided · payment.expired · payment.disputed
Treat webhooks as the source of truth for payment outcomes and use GET /payments/:id to confirm state on demand — see Webhooks.