Skip to content

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.

Code for Ways to create an order

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

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

Statuses

POST /orders · 202processingamount heldsucceededchargedunder_reviewstill heldfailedreleasedresolves to one of the two, never a second order
Where the money is in each status, and how an order under review ends.
StatusYour moneyWhat to do
ProcessingprocessingHeld. Delivery is in progress.Wait for the next state.
SucceededsucceededCaptured. The order is paid for.Nothing. completed_at is set.
FailedfailedReleased back to available.Read status_reason; order again if it makes sense.
Under reviewunder_reviewYour 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.

ReasonMeaning
Provider rejectedprovider_rejectedThe provider refused the delivery.
Recipient not eligiblerecipient_not_eligibleThe recipient cannot receive this product.
Not submitted price expirednot_submitted_price_expiredThe locked price expired before the order was submitted; nothing was sent.
Outcome unconfirmedoutcome_unconfirmedThe delivery was submitted but its outcome could not be confirmed.
Submission unconfirmedsubmission_unconfirmedIt could not be confirmed whether the delivery was submitted.
Provider conflictprovider_conflictThe provider reported a state that conflicts with the order.
Code for Status reasons
A failed order
JSON
200 OKSynthetic sandbox data
{  "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 reference is 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_capture and order_release movement names its order_id.
Code for Finding orders
GET /v1/ordersSandbox, test key
// 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. amount is cents: 750 is $7.50. A USD balance_after.amount_minor is 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 version is the newer state.
  • Treating estimated_completion_at as a deadline. It is an estimate from the queue. An order that passes it is still in progress.