Cancel a 0Gate session
POST /gate_sessions/{id}/cancel - Cancel an open session and branch safely on state conflicts.
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.
Cancelling marks an open session cancelled so the widget can no longer act on it. A session that has already reached a terminal state (completed, expired, or cancelled) cannot be cancelled and returns a conflict.
Endpoint
| Field | Value |
|---|---|
| Method | POST |
| Path | /v1/gate_sessions/{id}/cancel |
| Area | Sessions |
| Operation id | cancelSession |
| Auth boundary | Secret key from your server. |
The full request URL is https://gate-api.0bit.app/v1/gate_sessions/{id}/cancel. The {id} path parameter is a session id you own.
Use it for
Cancel an open session and branch safely on state conflicts.
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. - Only an
opensession cancels. A terminal session returns409— treat it as a benign state conflict, not a failure to retry blindly. - A session that belongs to a different partner returns
404, never403. - Branch on machine-readable status, error code, object id, and request id.
- Treat examples and placeholder ids as fake data only.
Request
There is no request body.
| Parameter | In | Required | Type | Use it for |
|---|---|---|---|---|
id | path | Yes | string | The open session id to cancel. |
| Header | Required | Use it for |
|---|---|---|
Authorization | Yes | Bearer sk_test_… or Bearer sk_live_…. |
Response
On success the server returns HTTP 201 Created with the GateSession, now with status: cancelled. The shape matches retrieve and never includes client_secret.
| Field | When present | Use it for |
|---|---|---|
id | Always | The session id. |
object | Always | gate_session discriminator. |
status | Always | Now cancelled. |
| … | Always | All other GateSession fields, unchanged. |
Cancel is only valid from open
Cancelling a completed, expired, or already-cancelled session returns 409 conflict. Read the current status from retrieve and treat the terminal state as authoritative — do not retry the cancel.
Examples
curl -X POST \
https://gate-api.0bit.app/v1/gate_sessions/67a1f3b9e4b0c10001234567/cancel \
-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": "cancelled",
"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": {}
}{
"type": "conflict",
"code": "conflict",
"message": "Example conflict error using fake data.",
"request_id": "req_test_000000000123",
"doc_url": null,
"statusCode": 409
}The session was already terminal (completed, expired, or cancelled). Read its status and stop retrying.
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.
| 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. |
409 | conflict | The session is already terminal (completed, expired, or cancelled); only an open session cancels. |
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.