Recipient lookup and confirmation
Show your customer the Telegram account behind a username, with its name and photo, before you quote Stars or Premium.
Sandbox: test money only. No request moves real money.
A recipient lookup resolves a Telegram username to the account found there: its display name and, when available, its profile image. Your customer sees the account and confirms it before you quote, so an order never goes to a mistyped username. It works for Telegram Stars and Telegram Premium, is read-only, and moves no money.
Availability: Available. Live and verified in production. Nothing reaches Telegram there: the test usernames choose the answer. A lookup is recommended and not required: without one, a quote checks the recipient itself.
What you send
Send the selection you will quote, because the answer is for one product and selection. Call it from your server, as every request.
| Field | Description |
|---|---|
| Productproduct · string · required | telegram_stars or telegram_premium. |
| Telegram usernametelegram_ | The username as your customer types it: name, @name, or a t.me/name link, with or without its scheme: 5 to 32 letters, digits and underscores. It is normalised for you, and the answer carries the normalised form. |
| Quantityquantity · integer | Stars only, and required for Stars: the quantity you will quote. |
| Monthsmonths · integer | Premium only, and required for Premium: 3, 6 or 12, the months you will quote. |
There is no Idempotency-Key: a repeated lookup of the same username, product and selection is answered from your own recent answer without asking the provider again (an account found within 30 seconds, nobody found within 60). It draws on its own rate limit buckets, lookups per key and lookups_org and lookups_daily per organisation, not on the quote buckets.
// 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})`);}What it returns
201 Created with the account found:
| Field | Description |
|---|---|
| IDid · string · required | The recipient reference: rlk_ and 26 characters. Cite it as recipient_lookup when you quote. It is your organisation's alone and bound to this username, product and selection. |
| Foundfound · boolean · required | Always true: an account was found at the username. It does not say who the account belongs to. |
| Resolution statusresolution_ | The lookup status. Always found on a 201; every other outcome is an error with its own code, below. |
| Product eligibilityproduct_ | Always not_refused: the provider did not refuse this account for this product and selection. It is not a promise of delivery. |
| Telegram usernametelegram_ | The normalised username, as quotes and orders carry it. |
| Display namedisplay_ | The name the provider returned, cleaned of control characters, at most 64 characters. Null when it returned none. |
| Photo URLphoto_ | The profile image, when available: an https address on a Telegram image host. Null when the provider returned none, or returned anything else. Load it in an image element only, and draw initials when it is null. |
| Productproduct · string · required | The product you looked up for. |
| Selectionselection · object · required | The quantity or months you looked up for. |
| Expires atexpires_ | Until when a quote may cite this lookup: 10 minutes after it was made. |
| Created atcreated_ | When the lookup was made. |
| Lookup sourcelookup_ | Who answered: provider, the Telegram provider's read-only search (always on Live, and on the sandbox while Nasfam has real lookups on, for any name outside nasfam_test_), or simulated, the sandbox's simulator, whose account is a sample. On the sandbox the quote, the order and its delivery stay synthetic either way. |
Nothing else is returned, because the provider returns nothing else: no stable account id and no statement of eligibility. Call it "Account found", never "Verified": a lookup does not prove who owns an account, so your customer stays the one who confirms.
The confirmation flow
- Look the recipient up with
POST /recipient-lookups. - Show your customer the
display_nameand thephoto_url(initials when it is null), and ask them to confirm the account. - Quote with
POST /quotes, citing the lookup'sidasrecipient_lookup. The quote is refused unless the lookup is yours, unexpired, for the same username, product and selection, and the account at the username is still the one found. The quote echoesrecipient_lookup. - Create the order from the quote with
POST /ordersand anIdempotency-Key. The order shows itsrecipient_lookup; events and webhooks do not carry it. - If a quote or an order answers
lookup_expiredorrecipient_mismatch, nothing was held: look the recipient up again and show the account again. A retry of an order with the same key and body returns the first order, however old its lookup.
Errors
| Code | When, and what to do |
|---|---|
| Invalid requestinvalid_ | The username is not a username, or the selection is not one the product sells. param names the field. Fix the value. Do not retry as it is. |
| Unknown fieldunknown_ | The body carries a field the lookup does not take. Remove the field. |
| Recipient not foundrecipient_ | The provider says nobody has this username. Ask your customer to check the username. |
| Recipient not eligiblerecipient_ | The account cannot receive this product. On Live, every nasfam_test_ name. Do not quote this recipient. |
| Product unavailableproduct_ | The product is closed, or no lookup serves it. Read GET /products, and offer only what is available. |
| Rate limitedrate_ | Past your own lookup buckets. Wait for Retry-After, then look up again. |
| Provider unavailableprovider_ | The provider timed out, failed, or limited the requests Nasfam may send it. It never means the username is free. Wait for Retry-After (2 seconds, or 30 when the provider limited Nasfam), then look up again. |
| Not foundnot_ | A quote cites a lookup that is not your organisation's, not in this environment, or not found. Cite the id of a lookup you made. |
| Lookup expiredlookup_ | A quote or an order cites a lookup past its expires_at. Nothing is held. Look the recipient up again and show your customer the account again. |
| Recipient mismatchrecipient_ | The quote is for another username, product or selection, the account at the username changed since the lookup, or an order cites a lookup its quote was not made from. Nothing is held. Look the recipient up again and show the account again. |
| Recipient lookup requiredrecipient_ | Only once citing a lookup is made mandatory: a quote, or a direct order, that cites none. Look the recipient up first, and cite it. |
| Idempotency key reusedidempotency_ | An order cites another lookup under an Idempotency-Key already used: that is another request. Use a new key for the new lookup. |
As on every request, a lookup can also be refused with invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, browser_request_refused, payload_too_large, unsupported_media_type, internal_error, service_unavailable. A lookup needs the same right as creating a quote. A timeout of your own call means unknown: look up again, which is safe because a lookup moves no money.
Test usernames
On the sandbox host, these usernames choose the lookup's answer. Every other username is found, with the display name Sandbox user @ and the username, and no photo. Live refuses every nasfam_test_ name with recipient_not_eligible.
| Username | Answer |
|---|---|
| Foundnasfam_ | An account, without a photo. |
| Found, with a photonasfam_ | An account, with a photo_url. |
| Nobody therenasfam_ | recipient_not_found. |
| Provider timeoutnasfam_ | provider_unavailable, retry after 2 seconds: the provider did not answer in time. |
| Provider failurenasfam_ | provider_unavailable, retry after 2 seconds: the provider failed. |
| Provider limitnasfam_ | provider_unavailable, retry after 30 seconds: the provider limited Nasfam. |
| Expired lookupnasfam_ | Found, already expired: a quote citing it is refused with lookup_expired. |
| Account changednasfam_ | Found; the account at the username changes before the quote, which is refused with recipient_mismatch. |
Quoting without a lookup
A quote that cites no lookup checks the recipient itself, before any money moves:
recipient.foundandrecipient.display_namecome back on the quote only.recipient_not_foundmeans nobody has this username, and nothing is reserved.recipient_not_eligiblemeans the recipient cannot receive this product.
Show the name on the quote to your customer before you order.
Related guides
- Quotes: the check a quote makes, and the price it holds.
- Orders and statuses: what follows a quote.
- Changelog: what this contract added.
