Skip to content

Learn recipient lookup

Show your customer the Telegram account behind the username they typed, and order only once they confirm it.

Sandbox: test money only. No request moves real money.

In this step you learn to look a Telegram username up and show your customer the account found, so an order never goes to a mistyped username. The step is optional: a direct order of Stars or Premium never needs it. The Sandbox answers with a sample account and nothing reaches Telegram.

The lookup is recommended, not required. An order checks the recipient itself, and refuses with nothing held when nobody has the username. The lookup lets your customer catch a mistyped username before they pay.

The flow

  1. Your customer types a Telegram username on your page.
  2. Your server looks the username up with POST /recipient-lookups, using your key.
  3. Your page shows the name, and the photo when there is one.
  4. Your customer confirms it is the account they mean.
  5. Your server creates the order.
  6. Your page shows the order's status until it is final.

Your page talks to your server, and your server talks to Nasfam Business. The API key is never in a page, an app or anything your customer can open.

Look the username up

POST /recipient-lookups is the one that returns what a confirmation screen shows: display_name and photo_url, each null when the provider returned none. Send the product, the telegram_username as your customer typed it, and the quantity or months you will sell. It moves no money and holds nothing.

GET /recipients/lookup is a shorter check: whether an account was found, its name when there is one, and whether the provider refused it for the product. It returns no photo and no id.

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 Look the username up

Look up a 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_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})`);}

Check a recipient

GET /v1/recipients/lookupSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: check } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/recipients/lookup',    {      params: {        username: 'nasfam_test_ok',        product: 'telegram_stars',      },      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_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})`);}

Show the account and ask

  • Show the display_name, the photo from photo_url, and the username with its @.
  • Load photo_url in an image element only. It is an address on a Telegram image host, and nothing else.
  • Ask one question: is this the account you mean? Offer a way to change the username beside the way to continue.
  • If your customer says it is the wrong account, let them correct the username and look it up again. Nothing has been priced or held.

In the Sandbox an ordinary username is found as a sample account named Sandbox user @ and the username, with no photo. nasfam_test_photo comes with a photo, nasfam_test_missing is nobody, and nasfam_test_lookup_unavailable is a provider that cannot answer: Recipient lookup lists every test username. Show all of it as test data.

Three cases to handle

CaseWhat the lookup answersWhat to show and do
No photo201 with photo_url null. display_name may be null too.Draw initials from the name in place of the photo. With no name either, show the username with its @. It is still an account found: ask your customer to confirm it.
Username not found422 recipient_not_found. The short check answers 200 with found false and the same reason.Tell your customer nobody has that username and let them correct it. Do not order. Nothing was held.
The provider cannot verify503 provider_unavailable, with Retry-After.It says nothing about the account, so never show "not found". Wait the seconds in Retry-After and look up again, or let your customer continue without the preview and show the username exactly as typed.

A username that is not a username at all (5 to 32 letters, digits or underscores) is refused with invalid_request at /telegram_username before the provider is asked.

A lookup is not proof of ownership

A lookup finds the account at a username. It does not prove who owns that account, and it is not a promise of delivery. Say "Account found", never "Verified", and let your customer be the one who confirms.

The provider returns no stable account id, so an account can change hands or names between the lookup and the order. Look up close to the purchase, and treat the order's own outcome as the truth.

What you should see

The lookup answers 201 with the account found. This is the Sandbox's sample account, so lookup_source is simulated and photo_url is null:

Code for What you should see
An account found in the Sandbox
JSON
201 CreatedSynthetic sandbox data
{  "id": "rlk_01K7SAMP000000000000000090",  "found": true,  "resolution_status": "found",  "product_eligibility": "not_refused",  "telegram_username": "nasfam_test_ok",  "display_name": "Sandbox user @nasfam_test_ok",  "photo_url": null,  "lookup_source": "simulated",  "product": "telegram_stars",  "selection": {    "quantity": 50  },  "expires_at": "2026-10-10T10:25:00.000Z",  "created_at": "2026-10-10T10:15:00.000Z"}

If it fails

What you seeWhat to check
recipient_not_foundNobody has this username. Ask your customer to check the spelling. Do not order.
provider_unavailableThe provider could not be asked. It says nothing about the account: wait the seconds in Retry-After, then look up again.
recipient_not_eligibleThe account cannot receive this product. On Live, every nasfam_test_ username answers this.
rate_limitedYou are past your lookup buckets. Wait the seconds in Retry-After. A lookup has its own buckets, apart from orders.
browser_request_refusedThe request came from a browser. Call the lookup from your server, and have your page call your server.

Next step

Sandbox step 4 of 7: Complete the guided test order. Place one Sandbox order from the dashboard, step by step, and see every part of an order before you write code.