Telegram Stars
Deliver Telegram Stars to a Telegram account from your prepaid balance: find the account, have your customer confirm it, then order and follow it to delivery.
Sandbox: test money only. No request moves real money.
Sell Telegram Stars to your own customers without integrating a Stars provider yourself. You send one order with the product, the username your customer gives you and how much, and follow it until it is delivered. When your customer should see the account or a price first, you look the account up and quote it before you order. Every order is paid from your prepaid business balance.
Availability: Available. Live and verified in production. Environments says which host and key a request uses, and whether it moves real money.
What you send
The product is telegram_stars. Send the recipient's telegram_username and a quantity. GET /products holds the bounds in force as selection: a min, a max and a step. They are provisional until they are confirmed, so read them rather than hard-coding them.
One order sends 50 to 100,000 Stars. For more, up to 1,000,000 Stars, place several orders. Each one is quoted and confirmed on its own. Give each order its own Idempotency-Key and reference, and follow each one to its own result.
// npm install axiosimport axios from 'axios';try { const { status, data: products } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ products', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, products);} 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 directly
Send POST /orders with product set to telegram_stars, the username your customer gave you and the quantity, with an Idempotency-Key you stored before sending. In one request the server checks the recipient, prices the order, checks your limits and your balance, and holds the amount. Nothing else is needed: no lookup, no quote and no id.
max_amount, in USD cents, is an optional ceiling on what the order charges. 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.
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.
To show your customer the account, or a price that holds, before they buy, use the advanced flow below.
// 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})`);}Advanced: confirm the account and lock a price
- Find the recipient behind the username your customer gives you, for the
quantityyou will sell. - Show your customer the account and ask them to confirm it.
- Quote it, citing the lookup they confirmed.
- Buy: create the order from the quote, with an
Idempotency-Key. - Track delivery until the order is
succeededorfailed.
Every request runs on your server, with your key. Your customer only sees your own screens.
Find the recipient
Send POST /recipient-lookups with product set to telegram_stars, the telegram_username exactly as your customer typed it (name, @name or a t.me/name link) and the quantity you will quote. The answer is the account found at that username: its display_name and photo_url as the provider returned them, the normalised telegram_username, and an id you cite later, valid until expires_at (10 minutes). A lookup moves no money and reserves nothing.
recipient_not_found: nobody has that username. Ask your customer to check the spelling.recipient_not_eligible: the account cannot receive Stars. Do not quote it.provider_unavailable: the provider could not be asked. It says nothing about the account: wait forRetry-After, then look it up again.invalid_requestat/telegram_username: not a username. A username is 5 to 32 letters, digits or underscores.
// npm install axiosimport axios from 'axios';try { const { status, data: lookup } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ recipient-lookups', { product: 'telegram_ stars', telegram_ username: 'nasfam_ test_ ok', quantity: 50, }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, lookup);} 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})`);}Show your customer the account
Show the display_name, the photo from photo_url in an image element (initials when it is null) and the username with its @, and ask your customer to confirm it is the account they mean. Say "Account found". Never call it verified: a lookup finds an account at a username and does not prove who owns it, so your customer is the one who confirms.
When display_name is null, show the username alone. If your customer says it is the wrong account, let them change the username and look it up again: nothing has been quoted or held.
On the sandbox host an ordinary username is found as a sample account (lookup_source is simulated), named Sandbox user @ and the username, with no photo; nasfam_test_photo comes with one. While Nasfam has real lookups on in the sandbox, it is looked up through the provider instead (lookup_source is provider), within tighter limits, and the quote and the order stay synthetic. Show either as test data. The test usernames choose every other answer.
Confirm, then quote
Once your customer confirms, send POST /quotes with the same telegram_username and quantity, and the lookup's id as recipient_lookup. The quote echoes recipient_lookup and holds its price for up to 60 seconds, until its expires_at. Show your customer the quote's price exactly as it is: the server prices every order, and Pricing and costs says how.
The quote is refused, and nothing is held, unless the lookup is yours, unexpired, for the same username and quantity, and the account at the username is still the one found:
lookup_expired: the lookup is past itsexpires_at. Look the recipient up again and show the account again.recipient_mismatch: the quote is for another username orquantity, or the account at the username changed since the lookup. Look it up again and show the account again.
// npm install axiosimport axios from 'axios';try { const { status, data: quote } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ quotes', { product: 'telegram_ stars', telegram_ username: 'nasfam_ test_ ok', quantity: 50, recipient_ lookup: 'rlk_ 01K7SAMP000000000000000090', }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, quote);} 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})`);}Buy
Send POST /orders with the quote's id as quote_id, the same recipient_lookup, and a new Idempotency-Key for this purchase. The amount is held on your balance when the order is accepted. Make the key before the first attempt and send the same key and body on every retry, a double click included: the answer is the first order again, marked Idempotent-Replayed, never a second order.
lookup_expired refuses an order whose lookup is past its expires_at, and quote_expired one whose quote has lapsed. Nothing is held either way: look the recipient up, or quote, again. A timeout of your own call is unknown, never failed: retry with the same key.
Give each purchase a reference of your own as well. If a call times out or answers 5xx, the order may exist: read GET /orders?reference= with it, or retry with the same key and body. Never create another order for the same purchase while the first one's outcome is unknown.
// 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_ 01K7SAMP000000000000000091', recipient_ lookup: 'rlk_ 01K7SAMP000000000000000090', reference: 'TEST-0002', }, { 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})`);}Track delivery
An order is processing until it is succeeded, when the amount held on your balance is captured, or failed, when the hold is released. under_review means its outcome is being checked and the money stays held: it is not final. Read an order with GET /orders/{id}, or receive its events at your webhook endpoint, and tell your customer it is delivered only at succeeded. See Order lifecycle.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "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"}Common mistakes
- Quoting a username nobody confirmed. Look the recipient up, show the account, and cite the lookup in the quote.
- Reading
provider_unavailableas not found. It says nothing about the account. Wait forRetry-After, then look it up again. - A new
Idempotency-Keyon a retry. Reuse the first attempt's key, so a retry can never be a second order. - Working out a price yourself. Show the quote's price; the server prices every order.
Related guides
- Telegram Premium: the same flow, in months.
- Recipient lookup: every field, error and test username of the lookup.
- Create a test order: one order, step by step.
- Recovering from failures: what to do when an answer is lost.
