Skip to content

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

HeaderValueSent
AuthorizationBearer nbk_test_...Required

No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.

Parameters

FieldDescription
Limitlimit · query integer1 to 100. Default 20.
Cursorcursor · query stringUp to 256 characters.
Statusstatus · query stringOne of processing, succeeded, failed, under_review.
Productproduct · query stringOne of telegram_stars, telegram_premium.
Referencereference · query stringPattern ^[^\u0000\uD800-\uDFFF]*$. Up to 64 characters.
Telegram usernametelegram_username · query stringOnly 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]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Created fromcreated[gte] · query stringFormat date-time. Pattern ^(?!0000-).*(?:[Zz]|[+-](?:0[0-9]|1[0-5]):[0-5][0-9])$.
Created beforecreated[lt] · query stringFormat date-time. Pattern ^(?!0000-).*(?:[Zz]|[+-](?:0[0-9]|1[0-5]):[0-5][0-9])$.
The request in cURL, JavaScript and Python
GET /v1/ordersSandbox, test key
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);
Code for Request
GET /v1/ordersSandbox, test key
// 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

StatusMeaningBody
OK200Orders, 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 requests429Too 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 statusdefaultError (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

FieldDescription
Has morehas_more · boolean · required
Next cursornext_cursor · string or null · required
Datadata · array of Order · required
IDdata[].id · string · requiredPattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$.
Environmentdata[].environment · string · requiredOne of live, sandbox.
Statusdata[].status · string · requiredOne of processing, succeeded, failed, under_review.
Status reasondata[].status_reason · string or nullStable 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[].product · string · requiredtelegram_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[].selection · Selection object · required
Quantitydata[].selection.quantity · integer
Monthsdata[].selection.months · integer
Recipientdata[].recipient · OrderRecipient object · required
Telegram usernamedata[].recipient.telegram_username · string · required
Amountdata[].amount · Money object · required
Amountdata[].amount.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencydata[].amount.currency · string · requiredUSD. One of USD.
Settlementdata[].settlement · object, one of 2Either 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[].quote_id · string or null
Recipient lookupdata[].recipient_lookup · string or nullThe recipient lookup this order's quote was bound to, or null. Not carried in events or webhooks.
Pricing versiondata[].pricing_version · string · required
Referencedata[].reference · string or null
Metadatadata[].metadata · Metadata objectUp to 20 keys.
Versiondata[].version · integer · requiredIncreases by one on every state change; order events by this. At least 1.
Estimated completion atdata[].estimated_completion_at · string or nullEstimate from the current queue and the approved provider rate; never a promise. Format date-time.
Created atdata[].created_at · string · requiredFormat date-time.
Updated atdata[].updated_at · string · requiredFormat date-time.
Completed atdata[].completed_at · string or nullFormat date-time.
Balance afterdata[].balance_after · objectOn the response that reserved the order only. The paying balance's available figure right after the reservation, from the ledger.
Currencydata[].balance_after.currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON.
Amount minordata[].balance_after.amount_minor · stringPattern ^(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).

Every kind of response
200 OKSynthetic sandbox data
{  "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}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "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}
Error
JSON
429 Too Many RequestsSynthetic sandbox data
{  "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
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyNot needed: a GET changes nothing, so it is safe to send again.
In the sandboxLists your sandbox orders. Your reference finds an order after a lost response.
On LiveThe same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. This request does not touch your balance.
Status changesNone.
Webhook eventsNone.

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.