List orders
GET/orders
List orders.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
Request
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.
Parameters
| Field | Description |
|---|---|
| Limitlimit · query integer | 1 to 100. Default 20. |
| Cursorcursor · query string | Up to 256 characters. |
| Statusstatus · query string | One of processing, succeeded, failed, under_review. |
| Productproduct · query string | One of telegram_stars, telegram_premium. |
| Referencereference · query string | Pattern ^[^\u0000\uD800-\uDFFF]*$. Up to 64 characters. |
| Telegram usernametelegram_ | Only orders for this recipient, matched exactly after the server normalises it as a quote does (@name, t.me/name and any letter case find name). Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?:/. Up to 64 characters. |
| Created fromcreated[gte] · query string | Format date-time. Pattern ^(?!0000-).. |
| Created beforecreated[lt] · query string | Format date-time. Pattern ^(?!0000-).. |
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ orders', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, },});if ( !response. ok) { const problem = await response. json(); throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}const result = await response. json();console. log( response. status, result);// npm install axiosimport axios from 'axios';try { const { status, data: orders } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ orders', { params: { reference: 'TEST-0001', limit: 10 }, headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, orders);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}Responses
| Status | Meaning | Body |
|---|---|---|
| OK200 | Orders, newest first. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>.
), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent.
). | object |
| Too many requests429 | Too many requests (rate_limited), or your queued orders are at your cap (queue_limit). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After.
. Headers: Request-Id, Retry-After (seconds to wait before retrying), RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>.
), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent.
). | Problem object |
| Any other statusdefault | Error (RFC 9457). A 503 service_unavailable with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe.
. Headers: Request-Id, Retry-After (on 429 and some 503 responses). | Problem object |
Fields of the 200 body
| Field | Description |
|---|---|
| Has morehas_ | |
| Next cursornext_ | |
| Datadata · array of Order · required | |
| IDdata[]. | Pattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$. |
| Environmentdata[]. | One of live, sandbox. |
| Statusdata[]. | One of processing, succeeded, failed, under_review. |
| Status reasondata[]. | Stable codes. New values may be added; treat unknown values as informational. Known values: provider_rejected, recipient_not_eligible, not_submitted_price_expired, outcome_unconfirmed, submission_unconfirmed, provider_conflict. |
| Productdata[]. | telegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium. |
| Selectiondata[]. | |
| Quantitydata[]. | |
| Monthsdata[]. | |
| Recipientdata[]. | |
| Telegram usernamedata[]. | |
| Amountdata[]. | |
| Amountdata[]. | USD, in cents. 0 to 100000000000. |
| Currencydata[]. | USD. One of USD. |
| Settlementdata[]. | Either shape 1: currency, asset, amount_nanogram, amount_gram, price_usd_micros, price_book_version, rounding, rate; or shape 2: currency, amount_usd_micros, amount_usd, price_usd_micros, price_book_version. |
| Quote IDdata[]. | |
| Recipient lookupdata[]. | The recipient lookup this order's quote was bound to, or null. Not carried in events or webhooks. |
| Pricing versiondata[]. | |
| Referencedata[]. | |
| Metadatadata[]. | Up to 20 keys. |
| Versiondata[]. | Increases by one on every state change; order events by this. At least 1. |
| Estimated completion atdata[]. | Estimate from the current queue and the approved provider rate; never a promise. Format date-time. |
| Created atdata[]. | Format date-time. |
| Updated atdata[]. | Format date-time. |
| Completed atdata[]. | Format date-time. |
| Balance afterdata[]. | On the response that reserved the order only. The paying balance's available figure right after the reservation, from the ledger. |
| Currencydata[]. | USD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON. |
| Amount minordata[]. | Pattern ^(0|[1-9][0-9]{0,18})$. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "data": [ { "id": "ord_ 01K7SAMP000000000000000001", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50, "months": 3 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 750, "currency": "USD" }, "settlement": { "currency": "USD", "amount_ usd": "7.500000", "amount_ usd_ micros": "7500000", "price_ usd_ micros": "7500000", "price_ book_ version": 1 }, "quote_ id": null, "recipient_ lookup": null, "pricing_ version": "sandbox-v1", "reference": null, "metadata": { "customer_ id": "c_ 8821" }, "version": 1, "estimated_ completion_ at": null, "created_ at": "2026-10-10T10:05:02Z", "updated_ at": "2026-10-10T10:05:02Z", "completed_ at": null, "balance_ after": { "currency": "USD", "amount_ minor": "17500000" } } ], "has_ more": false, "next_ cursor": null}{ "data": [ { "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z" } ], "has_ more": false, "next_ cursor": null}{ "type": "about:blank", "title": "Too many requests", "status": 429, "code": "rate_ limited", "category": "rate_ limit", "detail": "Too many requests. Retry after the time in Retry-After. ", "param": null, "request_ id": "req_ 01K7SAMP000000000000000090"}How it behaves
| What to expect | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Not needed: a GET changes nothing, so it is safe to send again. |
| In the sandbox | Lists your sandbox orders. Your reference finds an order after a lost response. |
| On Live | The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live. |
| Funding | None. This request does not touch your balance. |
| Status changes | None. |
| Webhook events | None. |
Error responses
Any request can answer with invalid_request, invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, rate_limited, service_unavailable, internal_error. Errors says what to do about each one.
