Retrieve a pay-out
GET /rails/pay_outs/{id} - Retrieve a partner-scoped pay-out record.
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.
Retrieving a pay-out returns the current state of a fiat disbursement your server initiated. Use it to follow a rail to settled, to reconcile against your own records, and to back up webhook callbacks with an authoritative server-side read.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/rails/pay_outs/{id} |
| Area | Rails |
| Operation id | retrievePayOut |
| Auth boundary | Secret key from your server. |
The {id} path parameter is a pay-out id returned by POST /rails/pay_outs. An id not scoped to this credential returns 404 — cross-tenant access is never 403.
Use it for
Retrieve a partner-scoped pay-out record and read its current status.
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 an
sk_*key — never apk_*publishable key. - Validate environment, mode, entitlement, asset, network, and amount before the call.
- Poll with bounded backoff; prefer webhooks for status transitions and use this read to confirm.
- 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 pay-out id returned when the record was created. |
| Header | Required | Use it for |
|---|---|---|
Authorization | Yes | Bearer sk_* secret key from your server. |
Response
Returns 200 with a rail_pay_out object.
| Field | When present | Use it for |
|---|---|---|
object | Always | Constant rail_pay_out for client-side type narrowing. |
id | Always | The pay-out id. |
kind | Always | Constant pay_out. |
status | Always | Lifecycle state: pending, processing, settled, failed, or cancelled. |
gate_session_id | Always | The session this pay-out belongs to. |
quote_id | Always | The redeemed signed quote. |
method | Always | The pay-out method derived from the quote. |
amount | Always | Signed, fee-inclusive amount the customer receives (base minus fees), as a decimal string. |
currency | Always | ISO 4217 fiat currency of amount. |
reference | Always | Your supplied reference, or null. |
created_at | Always | RFC 3339 timestamp the record was created. |
account_blocked | Conditional | true when this rail pushed the user past the cumulative volume cap; the account is blocked for future rails pending manual review. |
Branch on status, not on field presence
status is the single source of truth for where the rail is. Treat settled as terminal-success and failed/cancelled as terminal-failure; pending and processing are in-flight. Amounts are decimal strings, never floats.
Examples
curl https://gate-api.0bit.app/v1/rails/pay_outs/rpo_test_6f5e4d3c2b1a \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"object": "rail_pay_out",
"id": "rpo_test_6f5e4d3c2b1a",
"kind": "pay_out",
"status": "settled",
"gate_session_id": "gs_test_67a1f3b9e4b0c10001234567",
"quote_id": "qt_test_1a2b3c4d5e6f",
"method": "bank_transfer",
"amount": "98.75",
"currency": "EUR",
"reference": "withdrawal_test_001",
"created_at": "2026-01-01T00:00:00Z"
}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. |
403 | forbidden | Credential rejected, rail access not enabled, or mode mismatch. |
404 | not_found | The pay-out does not exist or is not scoped to this credential. Cross-tenant access is 404. |
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, administrative routes, settlement venues, and unsupported availability claims are outside the public API contract.