Skip to content

Telegram Premium

Gift Telegram Premium subscriptions of 3, 6 or 12 months 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 Premium subscriptions of 3, 6 or 12 months to your own customers. The flow is the one Telegram Stars uses: one order with the product, the username and the months, followed to delivery, or, when your customer should see the account or a price first, a lookup and a quote before the order. Every order is paid from your prepaid business balance.

Availability: Available. Live and verified in production. In the Sandbox orders are simulated. Environments says which host and key a request uses, and whether it moves real money.

In Live, Premium is sold to a workspace allowed to buy it. GET /products with your Live key lists it with available true when yours is; until then an order for it is refused and nothing is held.

What you send

The product is telegram_premium. Send the recipient's telegram_username and months: 3, 6 or 12. GET /products holds the months in force as selection.allowed. Check available and status there before you offer it: a client that reads them changes nothing when Premium opens.

Code for What you send
What can be ordered
JSON
200 OKSynthetic sandbox data
{  "data": [    {      "id": "telegram_stars",      "name": "Telegram Stars",      "status": "sandbox",      "provisional": true,      "available": true,      "selection": {        "type": "quantity",        "min": 50,        "max": 100000,        "step": 50      },      "recipient": {        "type": "telegram_username"      }    }  ],  "has_more": false,  "next_cursor": null}

If the account already has Premium

We cannot see in advance whether an account already has Telegram Premium: the lookup does not say. If Telegram refuses the gift, the order fails and the amount held for it is released once. Check status_reason.

Order directly

Send POST /orders with product set to telegram_premium, the username your customer gave you and the months, 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.

Code for Order directly
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})`);}

Advanced: confirm the account and lock a price

  1. Find the recipient behind the username your customer gives you, for the months you will sell.
  2. Show your customer the account and ask them to confirm it.
  3. Quote it, citing the lookup they confirmed.
  4. Buy: create the order from the quote, with an Idempotency-Key.
  5. Track delivery until the order is succeeded or failed.

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_premium, the telegram_username exactly as your customer typed it (name, @name or a t.me/name link) and the months 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 Premium. Do not quote it.
  • provider_unavailable: the provider could not be asked. It says nothing about the account: wait for Retry-After, then look it up again.
  • invalid_request at /telegram_username: not a username. A username is 5 to 32 letters, digits or underscores.
Code for Find the recipient
POST /v1/recipient-lookupsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: lookup } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/recipient-lookups',    {      product: 'telegram_premium',      telegram_username: '@nasfam_test_ok',      months: 3,    },    {      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 months, 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 months, and the account at the username is still the one found:

  • lookup_expired: the lookup is past its expires_at. Look the recipient up again and show the account again.
  • recipient_mismatch: the quote is for another username or months, or the account at the username changed since the lookup. Look it up again and show the account again.

Telegram Stars shows this request and its answer; for Premium, months takes the place of quantity.

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.

Telegram Stars shows this request and its answer; for Premium, months takes the place of quantity.

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.

Telegram Stars shows this request and its answer; for Premium, months takes the place of quantity.

Common mistakes

  • Quoting a username nobody confirmed. Look the recipient up, show the account, and cite the lookup in the quote.
  • Reading provider_unavailable as not found. It says nothing about the account. Wait for Retry-After, then look it up again.
  • A new Idempotency-Key on 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.