Skip to content

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.

Code for Send the order

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})`);}

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 workspace amount_usd_micros is exact. amount is the product line's price alone, in US cents.
  • status: processing. Accepted, not delivered yet. Only succeeded means 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.

Code for Read the answer
GET /v1/orders/{id}Sandbox, test key
// 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:

Code for What you should see
An accepted order
JSON
202 AcceptedSynthetic sandbox data
{  "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 seeWhat to check
insufficient_fundsThe order costs more than your available balance. Add test funds, then send the same request with the same key.
recipient_not_foundNo Telegram account has this username. Check the spelling.
key_environment_mismatchThe key and the host belong to different environments. Use a nbk_test_ key on the sandbox host.
idempotency_key_reusedYou sent this key before with a different body. Use one key per purchase, and never change the body between retries.
rate_limitedWait the seconds in Retry-After, then send the same request with the same key.
No answer: a timeout or a connection errorThe 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.