Sessions

A GateSession is the unit of work for one 0Gate checkout: a single buy, sell, or swap. You create it on your server with the amount and currency bound in, hand a browser-safe client_secret to the page that mounts the widget, and 0Gate drives the session to a terminal outcome and tells you about it over signed webhooks. Everything in a 0Gate integration — the iframe, the embed handshake, the settlement signal — hangs off this one object. If you understand the session, you understand the integration.

Think of it the way a Stripe Checkout Session works: a server-created, server-bound record that a browser-safe token unlocks for exactly one user, exactly once.

What a session represents

One session is one attempt to move money for one user. It carries:

• The economic terms — amount and currency, bound at creation on the server and not changeable from the browser.
• The flow — on_ramp (buy), off_ramp (sell), swap, or unlocked (the user picks a tab).
• The destination — optional target_token / target_network, plus return_url / cancel_url.
• Its own identity and lifecycle — a server-only id, a browser-safe client_secret, a status, and an expires_at.

A session is not a quote, a user, or a payment method. It is the container that ties one priced intent to one widget instance and one eventual webhook. The KYC, payment-method selection, fiat rails, and on-chain settlement all happen inside that container, run by 0Bit — you never assemble those screens yourself.

The GateSession object

Every read of a session returns the same shape. These are the fields the API guarantees (object is the discriminator gate_session; id, partner_id, mode, amount, currency, return_url, status, and expires_at are always present).

The raw client_secret is not part of this object — it appears only on the create response (see below). What 0Bit persists server-side is a client_secret_prefix plus a SHA-256 hash, never the plaintext.

Creating a session

You create a session with a secret key (sk_*) from your backend, against POST /v1/gate_sessions. The rate limit is 10 requests / minute / key, and an Idempotency-Key UUID is expected on every create.

curl -X POST https://gate-api.0bit.app/v1/gate_sessions \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "100.00",
    "currency": "EUR",
    "return_url": "https://app.example.com/return"
  }'

The response is the session, plus a one-time client_secret:

{
  "id": "67a1f3b9e4b0c10001234567",
  "object": "gate_session",
  "client_secret": "gsec_67a1f3b9e4b0c10001234567_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
  "amount": "100.00",
  "currency": "EUR",
  "status": "open",
  "expires_at": "2026-05-26T13:45:00Z"
}

Request parameters

Only three fields are required: amount, currency, and return_url. Everything else narrows or pre-fills the flow.

Created server-side — amount and currency can't be tampered with

The reason this matters is trust. Because the amount and currency are fixed on the server when the session is created, a hostile or buggy browser cannot change what the user is charged. The widget can only execute the terms the session was created with — if the iframe ever tries to transact a different amount, 0Gate rejects it. That rejection is tamper protection working as designed, not a bug in your integration.

This binding is enforced end to end: when the browser redeems the client_secret at bootstrap, the embed token comes back stamped with the session's amount, currency, target_token, target_network, and flow, and every subsequent iframe call is checked against those locked values. The browser receives the figures to render them, never to set them.

This is also why the create call needs a secret key and the page does not: minting the priced intent is a privileged, server-only operation. The browser only ever receives the client_secret, which can do nothing except open this session.

Create errors

The error envelope is the unified cross-product shape:

{
  "type": "...",
  "code": "...",
  "message": "...",
  "request_id": "...",
  "doc_url": null,
  "statusCode": 000
}

An X-Request-Id response header accompanies every response (matching request_id). Branch on the machine-readable type / code — never on the human-readable message, which may be a single string or an array of strings (validation) and can change without notice.

The client secret

Every session has two identifiers, and confusing them is the most common early mistake.

What each one is for

The id is your server-side handle. You store it, look up the session with it, cancel with it, and correlate webhooks against it. It is meaningless to a browser on its own — reading or cancelling a session requires the secret key.

The client_secret (gsec_<sessionId>_<random>, where the random part is 32 characters) is the browser-safe capability that binds the widget to exactly this session. You hand it to the page, the SDK exchanges your pk_* plus the client_secret at POST /v1/embed/bootstrap for a short-lived embed token, and the iframe runs the user through the flow. It is shown once, in the create response — capture it then. It carries no secret-key power: the worst a leaked client_secret can do is let someone open the same checkout the user was already going to see.

Shown once — capture it on create

0Bit never stores the raw client_secret. After create, the backend keeps only a prefix and a SHA-256 hash for lookup, so there is no API call that can return the plaintext again. A GET on the session returns the plain GateSession with no client_secret field. If you lose it before mounting the widget, you cannot recover it — create a fresh session instead.

The lifecycle

A session is created open and ends in exactly one terminal state. The browser callback is UX-only; the webhook is the source of truth.

Status enum

The status field is exactly one of four values. Three are terminal.

Terminal states are final. A session never moves out of completed, cancelled, or expired — to try again, create a new session.

Webhooks drive the state

State transitions are reported by signed POSTs to your webhook_url. The events documented in the spec are gate_session.created, .completed, .cancelled, .expired, and gate_session.kyc_package_accepted; the backend additionally emits gate_session.failed, kyc.required, and the operational partner.quota.warning / partner.quota.exhausted.

Event envelope

Every event is { id, type, created_at, data }:

• id — a UUID, stable across retries. Use it as your dedupe key.
• type — the event name (e.g. gate_session.completed).
• created_at — Unix epoch seconds at emission (an integer, not an ISO string).
• data — the full GateSession for created/cancelled/expired. For completed the session is augmented with tx_refid (the refid of the underlying transaction — join it to your order record or deep-link to the receipt). For kyc_package_accepted the payload is the redacted KycPackageAcceptance (session_id, partner_id, mode, provider, accepted_at, user_reference) — never raw KYC PII.

Verifying signatures

Verify every delivery before trusting it:

• Read the Gate-Signature header (value t=<unix>,v1=<hex>). It is HMAC-SHA256 over <timestamp>.<rawBody> keyed with your whsec_* secret, with a 300-second tolerance. (Never look for an x-0bit-signature header — it does not exist; the backend constant is locked to Gate-Signature.)
• Companion headers ride alongside it: X-0bit-Timestamp (same value as the t=), X-0bit-Event-Id (the dedupe UUID), and X-0bit-Event-Type. The User-Agent is 0bit-webhooks/1.0.
• The SDKs verify for you: client.webhooks.constructEvent(rawBody, header, secret) in Node, client.webhooks.construct_event(payload, sig_header, secret) in Python — both do a constant-time compare and throw/raise on mismatch.

Delivery & retries

Deliveries are enqueued per event and POSTed by a worker. A failed delivery retries on the schedule 1m → 5m → 30m → 2h, dead-lettering after 5 attempts. Because retries reuse the same event id, your handler must be idempotent — ack any 2xx (the body is ignored), dedupe on id, and reconcile via GET if you suspect a missed delivery.

See Authentication for the full signing and verification reference, and Webhooks for the event catalogue.

Retrieve and cancel

Two server-side operations let you inspect and end a session. Both take the session id and a secret key.

curl https://gate-api.0bit.app/v1/gate_sessions/67a1f3b9e4b0c10001234567 \
  -H "Authorization: Bearer $GATE_KEY"

curl -X POST https://gate-api.0bit.app/v1/gate_sessions/67a1f3b9e4b0c10001234567/cancel \
  -H "Authorization: Bearer $GATE_KEY"

See also