Send your own API order
One request that creates a sandbox order for Telegram Stars or Premium, then the order read back by its id.
Sandbox: test money only. No request moves real money.
In this step your own code creates one Sandbox order with your key, paid from the test funds you added in step 1. The money is synthetic and nothing reaches Telegram, so it is the safe way to prove the key, the host and your HTTP client all work.
This is the order Go Live counts: once it reads succeeded, your setup checklist marks the step done. An order from the dashboard never counts here.
Send the order
Every request carries the key as a bearer token in the Authorization header. There is no other credential and no session. An order also carries an Idempotency-Key header: one key per purchase, stored before you send, and the same key on every retry.
The body is the product, the Telegram username and how much: a quantity of Stars, or 3, 6 or 12 months of Premium. Choose your language and HTTP client at the top of the code panel; the choice holds on every page. The example reads the key from NASFAM_SANDBOX_KEY, which you set in the last step.
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.
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})`);}Read the answer
The server checks the recipient, prices the order and holds the amount on your balance, in one request. The answer is 202 with the order:
id: the order. Keep it to read the order again.settlement: what the order charges, held on your balance. For a USD workspaceamount_usd_microsis exact.amountis the product line's price alone, in US cents.status:processing. Accepted, not delivered yet. Onlysucceededmeans delivered.version: 1. It rises by one on every change of status.
Then read the order by its id to follow it to its end. Pick a quantity from the packages GET /prices lists: GET /products says which products you can order. Every order without a quote also draws on your organisation's quotes bucket, which all its keys share, as a quote does: Rate limits gives the figures.
Ignore any field or value you do not know. Responses gain new ones; a client that rejects them breaks for no reason.
// npm install axiosimport axios from 'axios';try { const { status, data: order } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ orders/ ord_ 01K7SAMP000000000000000090', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); 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})`);}When a request is refused
A refusal is a problem document with the media type application/problem+json. Branch on code, show detail to a person, and log request_id. Nothing is held when an order is refused. The example raises the problem with those fields in every language; its Error tab is the problem it would raise.
What you should see
The order answers 202 with its id, its settlement (what it holds) and status processing. Read it again by its id and it moves to succeeded:
{ "id": "ord_ 01K7SAMP000000000000000093", "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": null, "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}If it fails
| What you see | What to check |
|---|---|
insufficient_funds | The order costs more than your available balance. Add test funds, then send the same request with the same key. |
recipient_not_found | No Telegram account has this username. Check the spelling. |
key_environment_mismatch | The key and the host belong to different environments. Use a nbk_test_ key on the sandbox host. |
idempotency_key_reused | You sent this key before with a different body. Use one key per purchase, and never change the body between retries. |
rate_limited | Wait the seconds in Retry-After, then send the same request with the same key. |
| No answer: a timeout or a connection error | The outcome is unknown, not failed. Send the same request with the same key: it can only ever be the first order. |
Next step
Step 5 continues: Create a test order. Add test funds, see the amount held, and create one order that a retry can never duplicate.
Related concepts
- Authentication and keys: the header and the key format.
- Idempotency and safe retries: what a key binds, and for how long.
- Create an order: every field an order takes.
