Skip to content

Your first Live order

One real Telegram Stars order on the Live host, a step at a time, from your key to the money it moved.

Sandbox: test money only. No request moves real money.

Every request on this page is written for Live: https://api.nasfampay.com/v1, with the key read from NASFAM_LIVE_KEY on your server. Showing Live here grants nothing: a Live key comes only from a workspace activated for Live.

1. Activate Live

Live is an activation the server grants your workspace, never a setting. An Owner or an Admin sends the application from the dashboard, after a sign-in within the last 5 minutes. The server reads three requirements itself:

  • A verified email.
  • An authenticator: two-step sign-in.
  • One completed Sandbox order.

It answers with one of four outcomes: approved, one item needed, a review by people, or declined with a reason. Complete Live activation explains the tiers and the checks. Once active, GET /account with a Live key reads kyb_status active.

Code for 1. Activate Live
GET /v1/accountLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: account } = await axios.get(    'https://api.nasfampay.com/v1/account',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, account);} 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})`);}

2. Create a Live key

In the dashboard, under Developers, API keys. In Live only an Owner or an Admin creates a key, after a sign-in within the last 5 minutes. It starts with nbk_live_ and is shown once.

There is no default scope. Give the key only what this order needs:

ScopeWhat it opens
Balance:readbalance:readGET /balance
Quotes:writequotes:writePOST /recipient-lookups, GET /recipients/lookup and POST /quotes
Orders:writeorders:writePOST /orders
Orders:readorders:readGET /orders and GET /orders/{id}
Transactions:readtransactions:readGET /balance/transactions, to reconcile
Webhooks:writewebhooks:writePOST /webhook-endpoints, only if you use webhooks

A key never holds a scope your role lacks. You may also name the products a key may buy; the key's page says whether that list is applied to orders yet.

Store the key in your secret manager, or in the NASFAM_LIVE_KEY environment variable of the server that calls the API, apart from NASFAM_SANDBOX_KEY. Never put it in browser JavaScript, a mobile app, a repository or a log. Every request sends it as Authorization: Bearer followed by the key.

3. Fund the balance

Fund your account with crypto. Once your deposit is verified, your available balance is updated. Send native GRAM on the TON network to your own deposit address. That is the one way a Live balance is funded: Add real funds shows the address, and Funding with GRAM every rule.

4. Read the balance

GET /balance answers in the ledger's own figures: available, held and pending_funding in cents with their currency, and usd with the same figures exactly, in micro-dollars. Read available before you order: it is what an order can spend now. The amount of an order in progress is reserved apart from it, and Funding your account defines every field of the answer.

Code for 4. Read the balance
GET /v1/balanceLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: balance } = await axios.get(    'https://api.nasfampay.com/v1/balance',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, balance);} 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})`);}

5. Check the recipient (optional)

GET /recipients/lookup with the username and the product says whether an account was found and whether the provider refused it for this product. It returns no id: the order never needs it, and checks the recipient again itself.

Show your customer the name found, when there is one, and order only once they confirm it. "Found" means an account exists at that username; it never verifies who owns it.

Code for 5. Check the recipient (optional)
GET /v1/recipients/lookupLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: check } = await axios.get(    'https://api.nasfampay.com/v1/recipients/lookup',    {      params: { username: '@customer', product: 'telegram_stars' },      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, check);} 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})`);}

6. Create the order

POST /orders with the product (telegram_stars or telegram_premium), the username and quantity or months, and an Idempotency-Key. In one step the server checks the recipient, prices the order, checks your limits and your balance, and holds the exact amount.

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.

Without max_amount the server bounds the order: the price comes from its price book at fresh rates (or the order is refused with pricing_unavailable), and it must fit your organisation's order limit (order_limit_exceeded) and Live's per-order and daily USD limits. max_amount, in USD cents, adds your own strict ceiling: an order whose charge, its settlement, would be more is refused with price_changed, and nothing is held. 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.

  • One key per purchase. Make it, and store it with your reference and the body, before you send anything.
  • An uncertain retry reuses both. The same key and the same body answer 200 with Idempotent-Replayed: true and the order as it is now, never a second order.
  • 202 means accepted, not delivered. The order is processing and its amount is held. Track it; never send it again.
Code for 6. Create the order
POST /v1/ordersLive, real money
// 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://api.nasfampay.com/v1/orders',    {      product: 'telegram_stars',      username: '@customer',      quantity: 50,      reference: 'TEST-0002',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_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})`);}

7. Track it to the end

GET /orders/{id} is the truth. Read it again after a longer wait each time, at most every 30 seconds, until the status is final:

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.

A timeout while reading is not an outcome: read again. Unknown never means buy again.

Code for 7. Track it to the end
GET /v1/orders/{id}Live, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: order } = await axios.get(    'https://api.nasfampay.com/v1/orders/ord_01K7SAMP000000000000000090',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_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})`);}

8. Be told by webhook (optional)

Status reads are enough. A webhook tells you the same without asking: register an https:// endpoint for order.succeeded, order.failed and order.under_review, and store its secret, shown once.

  • Verify webhook-signature over the raw body with your secret before you parse it, and refuse a webhook-timestamp more than 5 minutes old.
  • Answer 2xx within 15 seconds, then do the work. Webhooks says what happens to a delivery that fails.
  • Record each webhook-id and ignore a repeat. Keep the highest version per order and ignore anything lower.
  • Read GET /orders/{id} before you release value. Webhooks has the receiver in every language.
Code for 8. Be told by webhook (optional)
POST /v1/webhook-endpointsLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: endpoint } = await axios.post(    'https://api.nasfampay.com/v1/webhook-endpoints',    {      url: 'https://example.com/webhooks/nasfam',      events: [        'order.succeeded',        'order.failed',        'order.under_review',        'funding.credited',      ],      description: 'Order updates',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, endpoint);} 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})`);}

9. Confirm the money

Reconcile three records that name the same order:

  • The order: succeeded, with completed_at set.
  • The statement: GET /balance/transactions shows an order_reserve that named the order_id when it was accepted, then an order_capture once it was delivered, or an order_release back to available if it failed.
  • The balance: held fell by the order's amount. A held amount becomes a charge only once delivery is verified.
Code for 9. Confirm the money
GET /v1/balance/transactionsLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: transactions } = await axios.get(    'https://api.nasfampay.com/v1/balance/transactions',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, transactions);} 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})`);}

Errors and recovery

What happenedCodeSafe to retry?What to do
The key is wrong, revoked or expiredinvalid_api_key, key_expiredNoCheck NASFAM_LIVE_KEY on your server. Create a new key if this one was revoked or expired.
A sandbox key reached the Live hostkey_environment_mismatchNoUse your Live key, which starts nbk_live_, on the Live host. Each key works on its own host only.
The key lacks a permissioninsufficient_scopeNoA key keeps the scopes it was made with. Create a key with the scope the request needs.
The balance cannot cover the orderinsufficient_fundsAfter fundingNothing was held. Fund the balance, then send the same order again.
The product is not open to youproduct_unavailable, product_not_permittedNoRead GET /products. Order only a product listed as available, with a key allowed to buy it.
The recipient is wrong or cannot receive itrecipient_not_found, recipient_not_eligibleNoNothing was held. Ask your customer to check the username. Live refuses every nasfam_test_ name.
The provider cannot answer nowprovider_unavailableYesWait the seconds in Retry-After, then send the same request. It is never read as not found.
The lookup or the quote expiredlookup_expired, quote_expiredNoNothing was held. Look up and quote again. The new order has a new body, so it gets a new key.
Too many requestsrate_limited, queue_limitYesWait the seconds in Retry-After, then send the same request with the same key.
No answer: a timeout or a dropped connectionNoneSame key onlyUNKNOWN, not failed. Send the same request with the same key, or find the order with GET /orders?reference=. Never a new order.
The first request with this key is still runningidempotency_in_progressSame key onlyWait, then send the same request with the same key.
A server error on the orderinternal_errorSame key onlyOn a request that changes your balance this is an unknown outcome. Send the same request with the same key.
The order is under_reviewA status, not an errorNeverThe money stays held while the outcome is confirmed. Show it as pending. It ends succeeded or failed; never order again.

Before you go live

The Go Live readiness checklist is the short list to make true first.

What you should see

The order answers 202 with status processing and version 1, then reads succeeded. Its amount moved from available to held and was captured on delivery.

Code for What you should see
An accepted Live order
JSON
202 AcceptedSynthetic sandbox data
{  "id": "ord_01K7SAMP000000000000000091",  "environment": "live",  "status": "processing",  "status_reason": null,  "product": "telegram_stars",  "selection": {    "quantity": 50  },  "recipient": {    "telegram_username": "customer"  },  "amount": {    "amount": 75,    "currency": "USD"  },  "quote_id": "quo_01K7SAMP000000000000000091",  "pricing_version": "example",  "reference": "TEST-0002",  "version": 1,  "estimated_completion_at": "2026-10-10T10:15:35.000Z",  "created_at": "2026-10-10T10:15:30.000Z",  "updated_at": "2026-10-10T10:15:30.000Z",  "completed_at": null,  "recipient_lookup": "rlk_01K7SAMP000000000000000090"}

If it fails

What you seeWhat to check
key_environment_mismatchA sandbox key reached the Live host. Use your nbk_live_ key, read from NASFAM_LIVE_KEY.
insufficient_fundsFund the balance first, then send the same order again.
recipient_not_eligibleA nasfam_test_ name, or an account the provider refuses for this product, reached Live. Use your customer's username.
No answer: a timeout or a dropped connectionThe outcome is unknown, not failed. Send the same request with the same key.

Next step

Step 4 continues: As one program. Every step of a first Live order in one program for your server, for Telegram Stars or Telegram Premium.