0Gate sessions
Create, retrieve, list, and cancel hosted 0Gate sessions with secret-key authentication, browser-safe client secrets, idempotency, and webhook reconciliation.
0Gate sessions are the primary public integration object for hosted buy, sell, and swap flows. Your server creates a session with a secret key, receives a session id and one-time browser-safe client_secret, and passes only the client secret to the browser. The browser uses that value with the 0Gate widget. Final state still comes from signed webhooks and trusted server reads.
Endpoints
| Method | Path | Operation id | Purpose |
|---|---|---|---|
GET | /gate_sessions | listSessions | Cursor-paginated session list for the authenticated partner. |
POST | /gate_sessions | createSession | Create a hosted session and return a browser-safe client_secret. |
GET | /gate_sessions/{id} | retrieveSession | Retrieve a session without returning the raw client_secret. |
POST | /gate_sessions/{id}/cancel | cancelSession | Cancel an open session. |
Create session
POST /gate_sessions binds the amount, currency, optional target asset/network, return URL, and your partner reference on the server. It is the safest way to prevent the browser from changing the economic terms of a hosted flow.
curl -X POST https://gate-api-sandbox.0bit.app/v1/gate_sessions \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 00000000-0000-4000-8000-000000000123" \
-d '{
"amount": "100.00",
"currency": "EUR",
"return_url": "https://partner.example/complete",
"cancel_url": "https://partner.example/cancel",
"target_token": "USDT",
"target_network": "arbitrum",
"flow": "on_ramp",
"user_reference": "user_test_123",
"metadata": {
"order_id": "order_test_123"
}
}'The response includes client_secret only on creation. Store the session id and your own order/reference id. Send client_secret to the browser, but never send the secret API key.
Read and cancel
| Operation | Behavior | Failure handling |
|---|---|---|
| List sessions | Returns partner-scoped sessions. Use cursor pagination with starting_after. | Log request id and retry only on retryable errors. |
| Retrieve session | Returns session shape without raw client_secret. | 404 means missing or not visible to this partner. |
| Cancel session | Marks an open session as cancelled. | 409 means already terminal; read current state and branch. |
State model
| Session state | Meaning | Partner action |
|---|---|---|
open | User can continue the hosted flow. | Show pending/in-progress state. |
completed | Hosted flow reached a completed state. | Fulfill only after verified webhook or trusted read. |
expired | Session can no longer be used. | Create a new session for a new attempt. |
cancelled | Session was cancelled intentionally. | Stop the flow and show a safe retry path. |
Idempotency
Create and cancel are state-changing writes. Send an Idempotency-Key and store it with your order. If a network timeout happens after creation, retry with the same key instead of creating a second session.
const session = await fetch(`${process.env.OBIT_GATE_BASE_URL}/gate_sessions`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.OBIT_GATE_SECRET_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': order.idempotencyKey,
},
body: JSON.stringify({
amount: '100.00',
currency: 'EUR',
return_url: 'https://partner.example/complete',
metadata: { order_id: order.id },
}),
});Reconciliation
Store these fields together:
| Field | Why |
|---|---|
| Session id | Primary 0Gate object. |
| Client secret hash/status | Confirms browser handoff without storing raw secrets. |
| Partner order id | Joins 0Bit state to your app. |
| Idempotency key | Prevents duplicate session writes. |
| Request id | Support traceability. |
| Webhook event id | Durable status transition and dedupe. |
Browser callbacks can update UI, but order fulfillment should wait for a verified webhook or trusted server-side read.