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.
// 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:
| Scope | What it opens |
|---|---|
| Balance:readbalance:read | GET /balance |
| Quotes:writequotes:write | POST /recipient-lookups, GET /recipients/lookup and POST /quotes |
| Orders:writeorders:write | POST /orders |
| Orders:readorders:read | GET /orders and GET /orders/{id} |
| Transactions:readtransactions:read | GET /balance/transactions, to reconcile |
| Webhooks:writewebhooks:write | POST /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.
// 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.
// 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
referenceand the body, before you send anything. - An uncertain retry reuses both. The same key and the same body answer 200 with
Idempotent-Replayed: trueand the order as it is now, never a second order. - 202 means accepted, not delivered. The order is
processingand its amount is held. Track it; never send it again.
// 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:
| 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. |
A timeout while reading is not an outcome: read again. Unknown never means buy again.
// 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-signatureover the raw body with your secret before you parse it, and refuse awebhook-timestampmore 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-idand ignore a repeat. Keep the highestversionper order and ignore anything lower. - Read
GET /orders/{id}before you release value. Webhooks has the receiver in every language.
// 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, withcompleted_atset. - The statement:
GET /balance/transactionsshows anorder_reservethat named theorder_idwhen it was accepted, then anorder_captureonce it was delivered, or anorder_releaseback toavailableif it failed. - The balance:
heldfell by the order's amount. A held amount becomes a charge only once delivery is verified.
// 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 happened | Code | Safe to retry? | What to do |
|---|---|---|---|
| The key is wrong, revoked or expired | invalid_api_key, key_expired | No | Check NASFAM_LIVE_KEY on your server. Create a new key if this one was revoked or expired. |
| A sandbox key reached the Live host | key_environment_mismatch | No | Use your Live key, which starts nbk_live_, on the Live host. Each key works on its own host only. |
| The key lacks a permission | insufficient_scope | No | A key keeps the scopes it was made with. Create a key with the scope the request needs. |
| The balance cannot cover the order | insufficient_funds | After funding | Nothing was held. Fund the balance, then send the same order again. |
| The product is not open to you | product_unavailable, product_not_permitted | No | Read GET /products. Order only a product listed as available, with a key allowed to buy it. |
| The recipient is wrong or cannot receive it | recipient_not_found, recipient_not_eligible | No | Nothing was held. Ask your customer to check the username. Live refuses every nasfam_test_ name. |
| The provider cannot answer now | provider_unavailable | Yes | Wait the seconds in Retry-After, then send the same request. It is never read as not found. |
| The lookup or the quote expired | lookup_expired, quote_expired | No | Nothing was held. Look up and quote again. The new order has a new body, so it gets a new key. |
| Too many requests | rate_limited, queue_limit | Yes | Wait the seconds in Retry-After, then send the same request with the same key. |
| No answer: a timeout or a dropped connection | None | Same key only | UNKNOWN, 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 running | idempotency_in_progress | Same key only | Wait, then send the same request with the same key. |
| A server error on the order | internal_error | Same key only | On a request that changes your balance this is an unknown outcome. Send the same request with the same key. |
The order is under_review | A status, not an error | Never | The 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.
{ "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 see | What to check |
|---|---|
key_environment_mismatch | A sandbox key reached the Live host. Use your nbk_live_ key, read from NASFAM_LIVE_KEY. |
insufficient_funds | Fund the balance first, then send the same order again. |
recipient_not_eligible | A 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 connection | The 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.
Related concepts
- Idempotency and safe retries: why one key can never pay twice.
- Recovering from failures: what to do in each case.
- Quotes: quote before purchase, to show your customer a price that holds.
