Getting started
Your first order in five steps: get a key, choose Stars or Premium, write the body, send it, and track it.
Sandbox: test money only. No request moves real money.
Five steps take you from a new key to a delivered sandbox order. The money is synthetic and nothing reaches Telegram.
Hosts, keys and headers
| Environment | Host and key |
|---|---|
| Sandboxsandbox | https:/, with a nbk_test_ key in NASFAM_SANDBOX_KEY. Test money only: nothing reaches Telegram or a blockchain. |
| Livelive | https://api.nasfampay.com/v1, with a nbk_live_ key in NASFAM_LIVE_KEY. Real money: an order spends your real balance and is delivered. |
A nbk_test_ key is a test credential, and anyone with an account creates one. A nbk_live_ key is a Live credential, and exists only for a workspace activated for Live. A key works on its own host only.
| Header | When, and what it carries |
|---|---|
| The keyAuthorization · required | Every request. Bearer followed by the whole key. There is no other credential and no session. |
| The retry keyIdempotency-Key | Every request that changes your balance, an order above all. One key per purchase, the same key on every retry. The examples read it from IDEMPOTENCY_KEY. |
A request body is JSON, sent with the application/json media type.
Use the selector under the title to write every example on these pages for Sandbox or for Live: the host and the key variable change together. Choosing Live grants nothing.
// npm install axiosimport axios from 'axios';try { const { status, data: account } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ account', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ 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})`);}1. Get an API key
Create your account and add test funds, then in your dashboard open Developers, then API keys, and create a key. A sandbox key starts with nbk_test_ and is shown once. Put it in the NASFAM_SANDBOX_KEY environment variable: every example here reads it from there.
Every request sends the key in the Authorization header as Bearer followed by the key. There is no other credential and no session. Keep the key on your server, never in a browser or an app.
2. Choose a product
| Product | `product` | How much |
|---|---|---|
| Telegram Stars | telegram_stars | A quantity of Stars. GET /products gives the range in force. |
| Telegram Premium | telegram_premium | months of Premium: 3, 6 or 12. |
Both are delivered to the Telegram username your customer gives you.
3. Configure the order
An order needs three fields and nothing else: no quote, no lookup and no id.
| Field | Description |
|---|---|
| Productproduct · string · required | telegram_stars or telegram_premium. The short forms stars and premium are accepted too. |
| Usernameusername · string · required | The Telegram username: name, @name or t.me/name. |
| Quantityquantity · integer | For Stars: how many. |
| Monthsmonths · integer | For Premium: 3, 6 or 12. |
| Max amountmax_ | Optional. The most the order may cost, as an amount in US cents with its currency of USD. |
Send quantity for Stars or months for Premium, never both. With max_amount, an order that would cost more is refused with price_changed and nothing is held.
To catch a mistyped username before your customer pays, you can check a recipient first. An order never needs it.
4. Send it
Send the body to POST /orders. In one request the server checks the recipient, prices the order and holds the amount on your balance. It answers 202 with the order:
id: the order. Keep it.settlement: what the order holds on your balance, every fee included.amountis the product line's price alone, in cents.status:processing. Accepted, not delivered yet.
The Idempotency-Key. The key goes in the Idempotency-Key header. Make one key for each purchase you intend, and store it before the first attempt. If the connection drops or the request times out, send the same request with the same key: you get the first order back, never a second one. A new purchase gets a new key. The key makes a retry safe, but it is not a promise of exactly-once delivery: when no answer comes, send the same request again or look the order up before you decide anything.
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})`);}5. Track it
Read the order by its id. status is the outcome, and only succeeded means delivered. A failed order delivered nothing, and its held amount goes back to your balance.
Reading it again is fine while you test. In production, register a webhook endpoint so each change of status comes to you.
// 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})`);}Related guides
- Your first Telegram Stars order: the whole order on one page, with the lookup, retries and the webhook handler.
- Your first Telegram Premium order: the whole order on one page, with the lookup, retries and the webhook handler.
- Add test funds: the same path as seven Sandbox steps, then five Live steps, one page each.
- Quotes: see and lock a price before you order.
- Funding your account: how an order holds its amount, then captures or releases it.
- Orders and statuses: every status, and where your money is in each.
- Recovering from failures: what to do when an outcome is unknown.
- Idempotency and safe retries: what a key binds, and for how long.
- Create an order: every field an order takes, in the API reference.
- Check a recipient: every field of the check, in the API reference.
- Complete Live activation: Live step 1, and the steps from there to a real order.
