Skip to content

Create order

POST/ordersChanges your balance

Create an order (funds are reserved before the response).

Sandbox: test money only. No request moves real money.

Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_....

Order from a quote (quote_id), or directly (product, telegram_username, max_amount). A direct order makes its own quote, so it draws on the organisation's quotes and quotes_daily buckets as well as orders, a replay of it included. The quickest order (draft.10, a USD organisation): {"product": "telegram_stars", "username": "@customer", "quantity": 100} or {"product": "telegram_premium", "username": "@customer", "months": 3}, with an Idempotency-Key. Nothing else is needed: no quote, no lookup, no id. In one step the server checks the recipient, prices the order from the same price book and functions a quote uses, checks your limits and available balance, and holds the exact amount. A price it cannot determine from fresh figures is 503 pricing_unavailable and nothing is held. max_amount (optional, USD in cents) is a ceiling: an order that would cost more is refused 409 price_changed at /max_amount and nothing is held. The order answered is the one GET /v1/orders/{id} returns; its product is the full product id (telegram_stars, telegram_premium) whichever name you sent. It draws on the quotes buckets as a direct order does. Retrying with the same Idempotency-Key and the same order (the same product, normalised username and selection, max_amount, reference and metadata) returns the first order (200, Idempotent-Replayed) and never holds or delivers twice; the same key with a different order is 422 idempotency_key_reused. On in the sandbox and in Live, for an organisation that spends USD or GRAM; one still on its legacy currency orders from a quote. The recipient is resolved inside the order, so it needs no lookup even where Nasfam requires one for quotes. The safe flow: look the recipient up (POST /v1/recipient-lookups), let your customer confirm, quote citing the lookup, then order with an Idempotency-Key. The order shows its lookup as recipient_lookup. A lookup past expires_at refuses the order with 409 lookup_expired and nothing is held; look the recipient up again. A retry with the same key and body returns the first order, however old its lookup. In the sandbox, the recipient chooses the outcome: each nasfam_test_ recipient's statuses, events and balance transactions are listed in x-nb-sandbox-scenarios. In Live every nasfam_test_ recipient is refused 422 recipient_not_eligible.

Careful. This operation changes your balance, which is synthetic money in the sandbox and real money on live. The Idempotency-Key header is required and is bound permanently to the operation it creates; reuse it on every retry of the same request. See Idempotency and safe retries.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired
Idempotency-Key3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0dRequired

Parameters

FieldDescription
Idempotency keyIdempotency-Key · header string · requiredBound permanently to the operation it created (an order, a simulated funding). Reuse it on every retry of the same request. Pattern ^[A-Za-z0-9_-]{16,64}$.

Body

One of 4 shapes. Unknown fields are rejected.

Order from quote

FieldDescription
Quote IDquote_id · string · requiredPattern ^quo_[0-9A-HJKMNP-TV-Z]{26}$.
Recipient lookuprecipient_lookup · objectThe lookup this quote was bound to, to have the order refused if it is any other: 409 recipient_mismatch. Part of the request an Idempotency-Key binds.
Referencereference · stringPattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters.
Metadatametadata · Metadata objectUp to 20 keys.

Order direct

FieldDescription
Productproduct · 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.
Telegram usernametelegram_username · string · requiredNormalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$.
Quantityquantity · integerBounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key. 1 to 1000000.
Monthsmonths · integerOne of 3, 6, 12.
Max amountmax_amount · Money object · required
Amountmax_amount.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencymax_amount.currency · string · requiredUSD. One of USD.
Recipient lookuprecipient_lookup · objectThe lookup your customer confirmed. The order's own quote is bound to it and refused as a quote citing it is. Part of the request an Idempotency-Key binds.
Referencereference · stringPattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters.
Metadatametadata · Metadata objectUp to 20 keys.

Order stars

FieldDescription
Productproduct · string · requiredOne of stars, telegram_stars.
Usernameusername · string · requiredA username as a customer types it: name, @name, t.me/name, or that link with its scheme. Normalised server-side (the @ or link removed, lower-cased); the answer carries the normalised username. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Quantityquantity · integer · requiredBounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split. 1 to 1000000.
Max amountmax_amount · UsdCeiling objectThe most this order may cost, in USD cents. An order that would cost more is refused 409 price_changed and nothing is held.
Amountmax_amount.amount · integerUSD, in cents. 1 to 100000000000.
Currencymax_amount.currency · stringAlways USD.
Referencereference · stringPattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters.
Metadatametadata · Metadata objectUp to 20 keys.

Order premium

FieldDescription
Productproduct · string · requiredOne of premium, telegram_premium.
Usernameusername · string · requiredA username as a customer types it: name, @name, t.me/name, or that link with its scheme. Normalised server-side (the @ or link removed, lower-cased); the answer carries the normalised username. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Monthsmonths · integer · requiredOne of 3, 6, 12.
Max amountmax_amount · UsdCeiling objectThe most this order may cost, in USD cents. An order that would cost more is refused 409 price_changed and nothing is held.
Amountmax_amount.amount · integerUSD, in cents. 1 to 100000000000.
Currencymax_amount.currency · stringAlways USD.
Referencereference · stringPattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters.
Metadatametadata · Metadata objectUp to 20 keys.
The request in cURL, JavaScript and Python
POST /v1/ordersSandbox, test keyIdempotency-Key required
// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');const response = await fetch('https://sandbox-api.nasfampay.com/v1/orders', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',    'Idempotency-Key': idempotencyKey,  },  body: JSON.stringify({ quote_id: 'quo_01K7SAMP000000000000000001' }),});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

Create an order

POST /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: order } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/orders',    {      product: 'telegram_stars',      username: 'nasfam_test_ok',      quantity: 50,      reference: 'TEST-0001',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, order);} 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})`);}

Create an order from a quote

POST /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: order } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/orders',    {      quote_id: 'quo_01K7SAMP000000000000000090',      reference: 'TEST-0001',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, order);} 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})`);}

Order for the confirmed recipient

POST /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: order } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/orders',    {      quote_id: 'quo_01K7SAMP000000000000000091',      recipient_lookup: 'rlk_01K7SAMP000000000000000090',      reference: 'TEST-0002',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, order);} 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})`);}

Order Telegram Stars

POST /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: order } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/orders',    {      product: 'telegram_stars',      username: 'nasfam_test_ok',      quantity: 50,    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, order);} 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})`);}

Order Telegram Premium

POST /v1/ordersSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: order } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/orders',    {      product: 'telegram_premium',      username: 'nasfam_test_ok',      months: 3,    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, order);} 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
OK200Replay of an earlier request with the same Idempotency-Key. Returns the order's current state. 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. ), Idempotent-Replayed.Order object
Accepted202Accepted. Funds are held and delivery is in progress. 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. ).Order object
Content too large413The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id.Problem 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

The order object

FieldDescription
IDid · string · requiredPattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$.
Environmentenvironment · string · requiredOne of live, sandbox.
Statusstatus · string · requiredOne of processing, succeeded, failed, under_review.
Status reasonstatus_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.
Productproduct · 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.
Selectionselection · Selection object · required
Quantityselection.quantity · integer
Monthsselection.months · integer
Recipientrecipient · OrderRecipient object · required
Telegram usernamerecipient.telegram_username · string · required
Amountamount · Money object · required
Amountamount.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencyamount.currency · string · requiredUSD. One of USD.
Settlementsettlement · 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 IDquote_id · string or null
Recipient lookuprecipient_lookup · string or nullThe recipient lookup this order's quote was bound to, or null. Not carried in events or webhooks.
Pricing versionpricing_version · string · required
Referencereference · string or null
Metadatametadata · Metadata objectUp to 20 keys.
Versionversion · integer · requiredIncreases by one on every state change; order events by this. At least 1.
Estimated completion atestimated_completion_at · string or nullEstimate from the current queue and the approved provider rate; never a promise. Format date-time.
Created atcreated_at · string · requiredFormat date-time.
Updated atupdated_at · string · requiredFormat date-time.
Completed atcompleted_at · string or nullFormat date-time.
Balance afterbalance_after · objectOn the response that reserved the order only. The paying balance's available figure right after the reservation, from the ledger.
Currencybalance_after.currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON.
Amount minorbalance_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
202 AcceptedSynthetic sandbox data
{  "id": "ord_01K7SAMP000000000000000001",  "environment": "sandbox",  "status": "processing",  "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"  }}

Not finished. Only a final status means it is done: read it again or wait for its webhook. An outcome that is not known yet is held, never a failure.

Code for Responses
Response
JSON
202 AcceptedSynthetic sandbox data
{  "id": "ord_01K7SAMP000000000000000090",  "environment": "sandbox",  "status": "processing",  "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": 1,  "estimated_completion_at": "2026-10-10T10:15:05.000Z",  "created_at": "2026-10-10T10:15:02.000Z",  "updated_at": "2026-10-10T10:15:02.000Z",  "completed_at": 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"}
Replay, same Idempotency-Key
JSON
200 OKSynthetic sandbox 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": "quo_01K7SAMP000000000000000090",  "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"}
Expired
JSON
409 ConflictSynthetic sandbox data
{  "type": "about:blank",  "title": "Recipient lookup expired",  "status": 409,  "code": "lookup_expired",  "category": "validation",  "detail": "This recipient lookup has expired. Look the recipient up again.",  "param": "/recipient_lookup",  "request_id": "req_01K7SAMP000000000000000091"}

How it behaves

What to expect
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyRequired, and bound permanently to what the first request made. Reuse it on every retry: a retry answers with the same operation, never a second one.
In the sandboxSynthetic money, and nothing reaches Telegram. A nasfam_test_ username chooses the outcome. See Sandbox scenarios.
On LiveA succeeded order delivers real value, paid from real money. A legacy-currency workspace orders from a quote. The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingThe order's amount must fit available. It moves to held before the response is sent.
Status changesStarts at processing, then succeeded, failed or under_review. A timeout means unknown: send the same request with the same key. See Order lifecycle.
Webhook eventsorder.accepted and order.processing, then order.succeeded, order.failed with order.refunded, or order.under_review.

For telegram_stars: One order sends 50 to 100,000 Stars. For more, up to 1,000,000 Stars, place several orders. Each one is quoted and confirmed on its own. GET /products holds the bounds in force.

Error responses

This operation can also answer with insufficient_funds, quote_expired, quote_already_used, price_changed, duplicate_reference, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, queue_limit, recipient_not_found, recipient_not_eligible, lookup_expired, recipient_mismatch, product_unavailable, pricing_unavailable, account_restricted, capacity_exhausted, order_limit_exceeded, spending_limit_reached, payload_too_large, unknown_field.

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.