Skip to content

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

EnvironmentHost and key
Sandboxsandboxhttps://sandbox-api.nasfampay.com/v1, with a nbk_test_ key in NASFAM_SANDBOX_KEY. Test money only: nothing reaches Telegram or a blockchain.
Livelivehttps://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.

HeaderWhen, and what it carries
The keyAuthorization · requiredEvery request. Bearer followed by the whole key. There is no other credential and no session.
The retry keyIdempotency-KeyEvery 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.

Code for Hosts, keys and headers
GET /v1/accountSandbox, test key
// 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 Starstelegram_starsA quantity of Stars. GET /products gives the range in force.
Telegram Premiumtelegram_premiummonths 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.

FieldDescription
Productproduct · string · requiredtelegram_stars or telegram_premium. The short forms stars and premium are accepted too.
Usernameusername · string · requiredThe Telegram username: name, @name or t.me/name.
Quantityquantity · integerFor Stars: how many.
Monthsmonths · integerFor Premium: 3, 6 or 12.
Max amountmax_amount · objectOptional. 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. amount is 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.

Code for 4. Send it

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

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.

Code for 5. Track it
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})`);}