Skip to content

The platform

What happens between
“pay” & “paid.”

Operators integrate once; their users just pick a payment method. This page is the anatomy of everything OmiCloud does in between: the contract you code against, the routing pass that picks a gateway, and the guarantees underneath both.

The machinery, up close
01How a payment moves

  1. Submitted

    You submit once

    Your backend calls one API for deposits and payouts, with an idempotency key: a retried request can never create a duplicate transaction.

  2. Processing

    We pick the path

    OmiCloud scores the eligible gateways for that payment method by your fees and rolling approval rate, then hands the transaction to the winner.

  3. Settled / Declined

    The gateway reports back

    Signed webhooks drive every status change, verified before anything else happens. On a decline or timeout, the cascade tries the next eligible gateway.

  4. History

    Every step on the ledger

    Each transition lands in an append-only event history, so you can always see where a payment stands and exactly how it got there.

02The contract

One call in. One webhook back.

The whole integration is a submission endpoint, a status lookup, and a webhook receiver on your side. Deposits and payouts share the same shape, and the shape doesn’t change when the gateway behind it does.

  • One reference tracks the transaction end to end
  • Idempotency-Key header makes retries safe
  • Webhooks signed and verified; polling as backup
The shape of it
POST /v1/payments
Idempotency-Key: 7d1f0c…

{
  "paymentMethod": "ewallet",
  "amount": 250.00,
  "currency": "USD",
  "operatorReference": "dep_88231"
}

→ 202 Accepted
{ "reference": "omi_tx_9f27c1", "state": "submitted" }

# later, on your webhook endpoint
x-omi-signature: hmac-sha256=…
{ "reference": "omi_tx_9f27c1", "state": "settled" }
03The routing pass

Three passes, one honest answer.

Routing only matters once a payment method has more than one connected gateway. When it does, every transaction gets the same three-pass treatment, and the pass that decides is built from your numbers, not ours.

Pass 1

Eligibility

Which gateways on the panel are eligible for this transaction? Region, currency and payment method filter the panel down before anything is scored.

  • Eligible gateways per method
  • Region & currency fit
  • Health check must pass
Pass 2

Scoring

The survivors are ranked on exactly two inputs: the fee you pay on that gateway, and its rolling-window approval rate for traffic like yours.

  • Your fee, not ours
  • Rolling approval rate
  • OmiCloud's margin excluded
Pass 3

Cascade

The winner gets the transaction. A decline or timeout doesn't end the story, the cascade steps down the ranking to the next eligible gateway.

  • Automatic on decline
  • Automatic on timeout
  • Every attempt on the ledger

Built like infrastructure. Because it is.

04The fine print, up front
Retries are safe
Idempotency keys mean a retried call replays the original response. It never double-submits.
Nothing gets through unverified
Every webhook is signature-verified before it can touch a transaction.
Silence gets flagged, not lost
A transaction that doesn't confirm inside its window is flagged for review, not left stuck with no visibility.
The state machine doesn't lie
Invalid transitions are rejected outright. A record can't skip from declined to settled.

Want to walk the contract with an engineer?

Bring your current flow and your worst decline day. We’ll map both onto the platform, endpoint by endpoint.

Book a demoAsk a question first