Retrieve a 0Gate transaction
GET /transactions/{refid} - Retrieve one partner transaction by reference id.
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.
Look up a single PartnerTransaction by its reference id. Use it to refresh the current status and amounts of an order you already know about — for support tooling, reconciliation, and confirming terminal state on your server rather than trusting browser callbacks.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/transactions/{refid} |
| Area | Transactions |
| Operation id | retrieveTransaction |
| Auth boundary | Secret key from your server. |
The {refid} path parameter is the transaction refid returned by GET /transactions and on your session records. A refid that belongs to another partner returns 404 — cross-tenant access is never distinguishable from a missing record.
Use it for
Retrieve one partner transaction by reference id. The lookup is scoped to the authenticated partner.
Use this endpoint only for the partner-scoped resource it describes. Store your own reference id, the returned refid, the request id, timestamps, and the current status so support and reconciliation do not depend on browser callbacks alone.
For local payment or payout rails, transaction records can include local_rail_transaction_id. Use that generic field for rail-side reconciliation; facilita_transaction_id may still appear as a deprecated compatibility alias on older records.
Production rules
- Keep secret keys on your server. This endpoint requires an
sk_*key. - Branch on machine-readable status, error code, object id, and request id.
- Poll sparingly with bounded backoff; prefer webhooks for state changes and use this endpoint to confirm.
- Treat a
404as "not found or not yours" — do not infer existence from it. - Treat examples and placeholder ids as fake data only.
Request
| Parameter | In | Required | Type | Use it for |
|---|---|---|---|---|
refid | path | Yes | string | The transaction reference id to retrieve. |
This is a GET with no query parameters and no request body.
Response
A single PartnerTransaction object. Every monetary and amount value is a decimal string, never a float.
| Field | Type | Use it for |
|---|---|---|
object | string | Always transaction. |
refid | string | Stable reference id for the transaction. Use it as the key in your ledger. |
session_id | string or null | The 0Gate session this transaction belongs to, or null if not linked to a session. |
action | string | BUY, SELL, or SWAP. See Action values. |
status | string | Current transaction status (free-form string, for example completed). Branch on the exact value. |
token | string | Crypto asset symbol, for example USDT. |
network | string | Settlement network for the token. |
currency | string | Fiat currency (ISO 4217), for example EUR. |
payment_method | string | The payment method used for the fiat leg. |
fiat_amount | string (decimal) | The fiat amount of the transaction. |
token_amount | string (decimal) | The crypto amount of the transaction. |
total_pay_or_receive | string (decimal) | All-in total the user pays (buy) or receives (sell), inclusive of fees. |
exchange_rate | string or null | Rate applied, as a decimal string, or null before it is known. |
total_fees | string or null | Total fees, as a decimal string, or null before they are known. |
created_at | string (ISO 8601) or null | When the transaction record was created, or null if not yet set. |
updated_at | string (ISO 8601) or null | When the record last changed, or null if not yet set. |
status_timeline | array | Ordered status checkpoints, each { "status": string, "at": ISO 8601 string }. |
Money and amount values are strings
fiat_amount, token_amount, total_pay_or_receive, exchange_rate, and total_fees are decimal strings. Parse them with a decimal-safe type; never with a binary float.
Action values
action | Meaning |
|---|---|
BUY | Fiat → crypto (on-ramp). |
SELL | Crypto → fiat (off-ramp). |
SWAP | Crypto → crypto conversion. |
Document all three actions
Treat action as one of BUY, SELL, or SWAP. SWAP is a valid value on live records even though it is not always enumerated alongside BUY and SELL — handle it explicitly so swap orders are not mishandled.
This is the REST shape — not the webhook shape
The transaction object embedded in session webhooks uses different field names (for example crypto_amount and total_paid_or_received). Do not map webhook fields onto this REST object or vice versa. If you cross-reference a receipt's local-rail settlement reference, use local_rail_transaction_id. Use the fields documented here for GET /transactions/{refid}.
Examples
curl https://gate-api.0bit.app/v1/transactions/0g_txn_abc123 \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"object": "transaction",
"refid": "0g_txn_abc123",
"session_id": "gs_test_000000000123",
"action": "SWAP",
"status": "completed",
"token": "USDT",
"network": "tron",
"currency": "EUR",
"payment_method": "balance",
"fiat_amount": "0.00",
"token_amount": "250.00",
"total_pay_or_receive": "249.40",
"exchange_rate": "0.9976",
"total_fees": "0.60",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:01:48Z",
"status_timeline": [
{ "status": "CREATED", "at": "2026-01-01T00:00:00Z" },
{ "status": "completed", "at": "2026-01-01T00:01:48Z" }
]
}{
"type": "not_found",
"code": "not_found",
"message": "Example error using fake data.",
"request_id": "req_test_000000000123",
"doc_url": null,
"statusCode": 404
}HTTP 404 — the refid does not exist or is not scoped to your credential. The two cases are indistinguishable by design.
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. |
403 | forbidden | Credential rejected — revoked key or mode mismatch. |
404 | not_found | Transaction not found, or not scoped to this partner. 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, rail providers, administrative routes, and unsupported availability claims are outside the public API contract.