Orders and statuses
The ways to create an order, the four states it can be in, and where your money is in each.
Sandbox: test money only. No request moves real money.
An order is one delivery of Stars or Premium to one Telegram username. It is created in one request and accepted with 202, with its amount held on your balance. It then moves on its own: the amount is captured if the order succeeds and released if it fails. The order record is what you reconcile against: the API has no receipt object.
Availability: Available. Live and verified in production.
Ways to create an order
Minimal. Send the product (telegram_stars or telegram_premium; stars and premium are accepted too), the username and how much (quantity or months), with an Idempotency-Key: the server checks the recipient, prices the order and holds the amount in one request. An organisation that does not spend USD orders from a quote. Getting started shows it.
A workspace that spends USD or GRAM orders this way. A workspace still on its legacy currency orders from a quote instead: spending_currency on GET /balance says which yours is.
From a quote. Create a quote first, read the recipient and the price, then send quote_id. A quote locks its price for up to 60 seconds and is used once. Past that you get quote_expired or quote_already_used.
Legacy-currency order. A workspace still on its legacy currency sends the product, the telegram_username, the selection (quantity for Stars, months for Premium) and a max_amount: the most you are willing to pay, in the minor unit of its currency. If the current price does not fit that ceiling, the order is refused with price_changed. A direct order is served only to a workspace still on its legacy currency; a USD or GRAM workspace orders from a quote.
Whichever form you use, the quantity must be one on sale: an order buys one of the packages GET /prices lists.
Every form takes an optional reference: up to 64 characters of letters, digits, ., _, : and -. A second order with the same reference is refused with duplicate_reference. Each takes metadata of your own: up to 20 keys of at most 40 characters, each with a text value of at most 500. Each requires an Idempotency-Key.
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})`);}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})`);}Statuses
| Status | Your money | What to do |
|---|---|---|
| Processingprocessing | Held. Delivery is in progress. | Wait for the next state. |
| Succeededsucceeded | Captured. The order is paid for. | Nothing. completed_at is set. |
| Failedfailed | Released back to available. | Read status_reason; order again if it makes sense. |
| Under reviewunder_ | Your funds stay held. | No action needed. |
Each state change increases version by one. When two signals disagree, a webhook and a poll for instance, the higher version is the newer truth, whatever the timestamps say.
Status reasons
status_reason is a stable code that says why an order is in its status, or null. The contract lists the values below without describing them, and without saying which status each accompanies; the meanings follow their names. New values may be added, so treat an unknown one as informational.
| Reason | Meaning |
|---|---|
| Provider rejectedprovider_ | The provider refused the delivery. |
| Recipient not eligiblerecipient_ | The recipient cannot receive this product. |
| Not submitted price expirednot_ | The locked price expired before the order was submitted; nothing was sent. |
| Outcome unconfirmedoutcome_ | The delivery was submitted but its outcome could not be confirmed. |
| Submission unconfirmedsubmission_ | It could not be confirmed whether the delivery was submitted. |
| Provider conflictprovider_ | The provider reported a state that conflicts with the order. |
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "failed", "status_ reason": "recipient_ not_ eligible", "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"}Finding orders
GET /orders lists orders newest first, 20 at a time (limit up to 100), with cursor for the next page. Filter by status, product, your reference, the recipient's telegram_username (matched after the server normalises it, so @name, t.me/name and any letter case find name), and a creation window with created[gte] and created[lt] (RFC 3339 timestamps). GET /orders/{id} returns one order.
- Your
referenceis the fastest way back to an order you created:GET /.orders?reference=TEST-0001 - The balance statement links the other way: every
order_reserve,order_captureandorder_releasemovement names itsorder_id.
// 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})`);}Limits
GET /account returns the one limit the server keeps: max_queued, the most orders that may be processing at once. With that many in progress, a further order is refused with queue_limit.
GET /limits returns the platform's limits and your workspace's own spending limits, with what each has used in the current day and month. An order a limit refuses answers spending_limit_reached and nothing is held. Every order also counts once against the daily quotes_daily request allowance (see Rate limits).
An order the balance cannot cover is refused with insufficient_funds, a product that is not orderable right now with product_unavailable, and a request made when no price can be computed with pricing_unavailable.
Common mistakes
- Reading an amount as a decimal.
amountis cents: 750 is $7.50. AUSDbalance_after.amount_minoris micro-dollars: "7500000" is $7.50. See Money fields. - Ordering again while one is under review. Under review is neither a failure nor a success, and its amount is still held. Wait for the final state.
- Sorting by time. Two updates can carry the same second. The higher
versionis the newer state. - Treating
estimated_completion_atas a deadline. It is an estimate from the queue. An order that passes it is still in progress.
Related guides
- Create a test order: one order in the sandbox, step by step.
- Sandbox scenarios: which outcomes you can cause, and how to test the others.
- Order lifecycle: every transition, and the event it raises.
- Funding your account: where the money is while an order is in progress.
- Idempotency and safe retries: one key, one order.
