Retrieve a 0Gate session
GET /gate_sessions/{id} - Read partner-scoped session state without returning the raw client secret.
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.
Read the current state of a single session your partner owns. Use it for server-side reconciliation and support — never to recover the client_secret, which is returned only when the session is created.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/gate_sessions/{id} |
| Area | Sessions |
| Operation id | retrieveSession |
| Auth boundary | Secret key from your server. |
The full request URL is https://gate-api.0bit.app/v1/gate_sessions/{id}. The {id} path parameter is a session id returned by create or list.
Use it for
Read partner-scoped session state without returning the raw client secret.
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 session that belongs to a different partner returns
404, never403— cross-tenant ids are never confirmed to exist. - Reconcile on the returned
status; do not depend on browser callbacks alone. - Branch on machine-readable status, error code, object id, and request id.
- Treat examples and placeholder ids as fake data only.
Request
| Parameter | In | Required | Type | Use it for |
|---|---|---|---|---|
id | path | Yes | string | The session id to read. Scoped to your partner. |
| Header | Required | Use it for |
|---|---|---|
Authorization | Yes | Bearer sk_test_… or Bearer sk_live_…. |
Response
Returns HTTP 200 with the GateSession object. The raw client_secret is never included — it is shown only once, on create.
Retrieve does not expire a session
Reading a session does not change its status. An open session past its expires_at is still reported open here; the transition to expired happens on the embed-bootstrap path, not on this read.
Response fields
| Field | When present | Use it for |
|---|---|---|
id | Always | The session id. |
object | Always | gate_session discriminator. |
partner_id | Always | The partner that owns the session. |
mode | Always | test or live. |
amount | Always | The bound amount, as a decimal string. |
currency | Always | The bound, uppercased ISO 4217 code. |
return_url | Always | The success redirect. |
cancel_url | Always | The cancel redirect, or null. |
status | Always | open, completed, expired, or cancelled. |
expires_at | Always | ISO-8601 expiry. |
created_at | Always | ISO-8601 creation time, or null. |
flow | Always | The locked flow, or null. |
target_token | Always | The token constraint, or null. |
target_network | Always | The network constraint, or null. |
wallet_address | Always | The pre-filled wallet, or null. |
user_reference | Always | Your opaque correlation id, or null. |
kyc_pre_verified | Always | true only when an accepted kyc_package was supplied at create. |
metadata | Always | Your opaque notes, returned verbatim. |
Status values
status | Terminal? | Meaning |
|---|---|---|
open | No | Accepting actions. |
completed | Yes | At least one intent against the session succeeded. |
expired | Yes | Past expires_at without completing. |
cancelled | Yes | The partner cancelled the session. |
Examples
curl https://gate-api.0bit.app/v1/gate_sessions/67a1f3b9e4b0c10001234567 \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"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": "order_abc123",
"kyc_pre_verified": false,
"metadata": {}
}No client_secret — it is returned only on create.
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": "not_found",
"code": "not_found",
"message": "Example not-found error using fake data.",
"request_id": "req_test_000000000123",
"doc_url": null,
"statusCode": 404
}| Status | type | When it happens |
|---|---|---|
401 | unauthorized | Missing or invalid secret key. |
404 | not_found | The session does not exist or is owned by another partner. Cross-tenant ids are 404, never 403. |
429 | rate_limited | Request throttled. Back off and retry. |
5xx | server_error | Transient server or upstream failure. Retry with bounded backoff. |
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.