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
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
Content-Type | application/json | Required |
Idempotency-Key | 3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0d | Required |
Parameters
| Field | Description |
|---|---|
| Idempotency keyIdempotency-Key · header string · required | Bound 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
| Field | Description |
|---|---|
| Quote IDquote_ | Pattern ^quo_[0-9A-HJKMNP-TV-Z]{26}$. |
| Recipient lookuprecipient_ | The 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 · string | Pattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters. |
| Metadatametadata · Metadata object | Up to 20 keys. |
Order direct
| Field | Description |
|---|---|
| Productproduct · string · required | 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. |
| Telegram usernametelegram_ | Normalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$. |
| Quantityquantity · integer | Bounded 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 · integer | One of 3, 6, 12. |
| Max amountmax_ | |
| Amountmax_ | USD, in cents. 0 to 100000000000. |
| Currencymax_ | USD. One of USD. |
| Recipient lookuprecipient_ | The 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 · string | Pattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters. |
| Metadatametadata · Metadata object | Up to 20 keys. |
Order stars
| Field | Description |
|---|---|
| Productproduct · string · required | One of stars, telegram_stars. |
| Usernameusername · string · required | A 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]?:/. Up to 64 characters. |
| Quantityquantity · integer · required | Bounded 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_ | The most this order may cost, in USD cents. An order that would cost more is refused 409 price_changed and nothing is held. |
| Amountmax_ | USD, in cents. 1 to 100000000000. |
| Currencymax_ | Always USD. |
| Referencereference · string | Pattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters. |
| Metadatametadata · Metadata object | Up to 20 keys. |
Order premium
| Field | Description |
|---|---|
| Productproduct · string · required | One of premium, telegram_premium. |
| Usernameusername · string · required | A 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]?:/. Up to 64 characters. |
| Monthsmonths · integer · required | One of 3, 6, 12. |
| Max amountmax_ | The most this order may cost, in USD cents. An order that would cost more is refused 409 price_changed and nothing is held. |
| Amountmax_ | USD, in cents. 1 to 100000000000. |
| Currencymax_ | Always USD. |
| Referencereference · string | Pattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters. |
| Metadatametadata · Metadata object | Up to 20 keys. |
// 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);Create an order
// 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
// 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
// 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
// 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
// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | Replay 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 |
| Accepted202 | Accepted. 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 large413 | The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id. | Problem 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 |
The order object
| Field | Description |
|---|---|
| IDid · string · required | Pattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$. |
| Environmentenvironment · string · required | One of live, sandbox. |
| Statusstatus · string · required | One of processing, succeeded, failed, under_review. |
| Status reasonstatus_ | 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. |
| Productproduct · string · required | 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. |
| Selectionselection · Selection object · required | |
| Quantityselection. | |
| Monthsselection. | |
| Recipientrecipient · OrderRecipient object · required | |
| Telegram usernamerecipient. | |
| Amountamount · Money object · required | |
| Amountamount. | USD, in cents. 0 to 100000000000. |
| Currencyamount. | USD. One of USD. |
| Settlementsettlement · object, one of 2 | 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 IDquote_ | |
| Recipient lookuprecipient_ | The recipient lookup this order's quote was bound to, or null. Not carried in events or webhooks. |
| Pricing versionpricing_ | |
| Referencereference · string or null | |
| Metadatametadata · Metadata object | Up to 20 keys. |
| Versionversion · integer · required | Increases by one on every state change; order events by this. At least 1. |
| Estimated completion atestimated_ | Estimate from the current queue and the approved provider rate; never a promise. Format date-time. |
| Created atcreated_ | Format date-time. |
| Updated atupdated_ | Format date-time. |
| Completed atcompleted_ | Format date-time. |
| Balance afterbalance_ | On the response that reserved the order only. The paying balance's available figure right after the reservation, from the ledger. |
| Currencybalance_ | USD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON. |
| Amount minorbalance_ | 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).
{ "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.
{ "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}{ "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"}{ "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"}{ "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 | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Required, 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 sandbox | Synthetic money, and nothing reaches Telegram. A nasfam_test_ username chooses the outcome. See Sandbox scenarios. |
| On Live | A 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. |
| Funding | The order's amount must fit available. It moves to held before the response is sent. |
| Status changes | Starts at processing, then succeeded, failed or under_review. A timeout means unknown: send the same request with the same key. See Order lifecycle. |
| Webhook events | order.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.
