Create a hosted checkout session

post

https://sandbox-api.omicloud.io/v1/sessions

Starts a deposit. OmiCloud creates the transaction, asks the
selected gateway for a hosted checkout, and returns the URL to send
your end user to. The end user pays on the gateway's page; OmiCloud
never touches the funds.

Omit gateway to let OmiCloud route. The response always says which
gateway was chosen.

Send an Idempotency-Key. A retried request with the same key returns
the original session instead of opening a second checkout.

The session expires at expiresAt. If nothing is deposited by then
the transaction is declined with declineReason: session_expired and
a session.expired event is sent.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

amount

string

required

^[0-9]+(\.[0-9]{1,8})?$

Decimal string. Up to 8 fractional digits. Never a float.

currency

string

required

network

string

paymentMethod

string

gateway

string

Force a gateway. Omit to let OmiCloud route.

country

string

length between 2 and 2

endUserId

string

Your id for the end user. Strongly recommended — it drives routing and lets you search by user.

operatorReference

string

length ≤ 128

Your own reference. Stored, returned on every read and event, searchable. Never used for logic.

redirectUrl

uri

Where the hosted page sends the end user afterwards. Domain must be allow-listed on your account.

metadata

object

Up to 20 string keys, 500 characters each. Returned as-is.

Headers

Omi-Version

string

^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Dated API version, e.g. 2026-09-01. Omit to use the version your API
key is pinned to. Only one version exists today; send the header
anyway so upgrades are a one-line change.

Idempotency-Key

string

length ≤ 255

Any string up to 255 characters, unique per operator. A retry with the
same key and the same body returns the original response with
Idempotent-Replayed: true. The same key with a different body is
rejected with 409 IDEMPOTENCY_KEY_REUSED. Keys are remembered for 24 h.

Responses

201Session created. Send the end user to url.

400The request is malformed or outside what any route can execute.

401Missing, malformed, revoked, or wrong-environment API key.

403The key lacks the scope, the operator is paused, or the gateway is not connected to this account.

409The Idempotency-Key was already used with a different body.

502The gateway failed or was unreachable. The transaction was created and is now declined; gatewayDetails carries what the gateway said.