Create a 0Gate session

0Gate is the primary public integration path for hosted payment, ramp, and swap experiences. Keep secret-key operations on your server and hand only browser-safe values to the widget.

A session binds an amount and currency server-side, then hands the browser a one-time client_secret. The browser presents that secret to the embed bootstrap to frame the widget against this exact, locked session. Create the session from your server with a secret key; the user never sees your sk_*.

Endpoint

The full request URL is https://gate-api.0bit.app/v1/gate_sessions.

Use it for

Create a hosted session and return the browser-safe client secret once.

Use this endpoint only for the partner-scoped resource it describes. Store your own reference id, the returned 0Bit object id, the request id, timestamps, and the current status so support and reconciliation do not depend on browser callbacks alone.

Production rules

• Keep secret keys on your server. This endpoint requires a sk_* key. A pk_* publishable key is browser-only and used solely for the embed bootstrap.
• Validate environment, mode, entitlement, asset, network, and amount before the call.
• Send an Idempotency-Key for the logical write and retry timeouts with the same key.
• Capture client_secret on this create response — it is returned once and never appears on retrieve or list.
• Branch on machine-readable status, error code, object id, and request id.
• Treat examples and placeholder ids as fake data only.

Request headers

Request body

Response

On success the server returns HTTP 201 Created with the GateSession object plus a one-time client_secret.

Response fields

Examples

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

{
  "id": "67a1f3b9e4b0c10001234567",
  "object": "gate_session",
  "partner_id": "507f1f77bcf86cd799439011",
  "mode": "test",
  "amount": "100.00",
  "currency": "EUR",
  "return_url": "https://partner.example/checkout/done",
  "cancel_url": null,
  "status": "open",
  "expires_at": "2026-05-27T12:00:00.000Z",
  "created_at": "2026-05-26T12:00:00.000Z",
  "flow": null,
  "target_token": null,
  "target_network": null,
  "wallet_address": null,
  "user_reference": null,
  "kyc_pre_verified": false,
  "metadata": {},
  "client_secret": "gsec_67a1f3b9e4b0c10001234567_AbCdEfGhIjKlMnOpQrStUvWxYz012345"
}

{
  "id": "67a1f3b9e4b0c10001234999",
  "object": "gate_session",
  "partner_id": "507f1f77bcf86cd799439011",
  "mode": "test",
  "amount": "250.00",
  "currency": "EUR",
  "return_url": "https://partner.example/checkout/done",
  "cancel_url": null,
  "status": "open",
  "expires_at": "2026-05-27T12:00:00.000Z",
  "created_at": "2026-05-26T12:00:00.000Z",
  "flow": "on_ramp",
  "target_token": "USDC",
  "target_network": "ETHEREUM",
  "wallet_address": null,
  "user_reference": "order_abc123",
  "kyc_pre_verified": false,
  "metadata": {},
  "client_secret": "gsec_67a1f3b9e4b0c10001234999_ZyXwVuTsRqPoNmLkJiHgFeDcBa987654"
}

Errors

All errors use the unified envelope and carry an X-Request-Id response header. Branch on code/type/statusCode, not on the free-form message.

{
  "type": "forbidden",
  "code": "kyc_package_not_trusted",
  "message": "Example forbidden error using fake data.",
  "request_id": "req_test_000000000123",
  "doc_url": null,
  "statusCode": 403
}

Public boundary

This reference covers partner-scoped endpoint behavior, authentication, idempotency, webhook verification, and support-safe records. Internal operations, settlement venues, fiat-rail providers, KYC vendors, administrative routes, and unsupported availability claims are outside the public API contract.

Related pages