Skip to content

Create quote

POST/quotes

Verify a recipient and lock a price for up to 60 seconds.

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

Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_....

Cite the recipient lookup your customer confirmed as recipient_lookup (recommended). The quote is then refused unless the lookup is this organisation's (404 not_found otherwise), unexpired (409 lookup_expired) and for the same username, product and selection, and the account the provider finds at the username now is the one the lookup found (409 recipient_mismatch). Without it the quote checks the recipient itself, as before. recipient_lookup is not part of the Idempotency-Key's request: a replay returns the first quote as it was made. In the sandbox, nasfam_test_missing is refused 422 recipient_not_found and every other nasfam_test_ recipient chooses the order's outcome (x-nb-sandbox-scenarios). In Live every nasfam_test_ recipient is refused 422 recipient_not_eligible.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired
Idempotency-Key3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0dOptional

Parameters

FieldDescription
Idempotency keyIdempotency-Key · header stringBound permanently, in the database, to what the first request made (a quote, an endpoint, a rotation, a delivery replay), as a money operation's key is: a retry with the same key and request answers 200 with Idempotent-Replayed: true and repeats nothing, and the same key with another request or on another operation is 422 idempotency_key_reused. A replay never returns a secret. Without a key, every request is performed. Pattern ^[A-Za-z0-9_-]{16,64}$.

Body

One of 2 shapes. Unknown fields are rejected.

product is telegram_stars

FieldDescription
Productproduct · string · requiredAlways telegram_stars.
Telegram usernametelegram_username · string · requiredNormalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$.
Quantityquantity · integer · requiredBounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key. 1 to 1000000.
Recipient lookuprecipient_lookup · stringPattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$.
Pay withpay_with · stringA USD organisation always pays in USD; both values mean that. One of auto, usd.

product is telegram_premium

FieldDescription
Productproduct · string · requiredAlways telegram_premium.
Telegram usernametelegram_username · string · requiredNormalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$.
Monthsmonths · integer · requiredOne of 3, 6, 12.
Recipient lookuprecipient_lookup · stringPattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$.
Pay withpay_with · stringA USD organisation always pays in USD; both values mean that. One of auto, usd.
The request in cURL, JavaScript and Python
POST /v1/quotesSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/quotes', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    product: 'telegram_stars',    telegram_username: 'nasfam_test_ok',    quantity: 50,  }),});if (!response.ok) {  const problem = await response.json();  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}const result = await response.json();console.log(response.status, result);
Code for Request

Quote the confirmed recipient

POST /v1/quotesSandbox, test key
// 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})`);}

Create a quote

POST /v1/quotesSandbox, test key
// 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,    },    {      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})`);}

Responses

StatusMeaningBody
OK200A replay of an earlier request with the same Idempotency-Key: the quote it made, unchanged (it may have expired since). Nothing is priced again. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ), Idempotent-Replayed.Quote object
Created201Quote created. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).Quote object
Content too large413The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id.Problem object
Too many requests429Too many requests (rate_limited), or your queued orders are at your cap (queue_limit). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After. . Headers: Request-Id, Retry-After (seconds to wait before retrying), RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).Problem object
Any other statusdefaultError (RFC 9457). A 503 service_unavailable with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe. . Headers: Request-Id, Retry-After (on 429 and some 503 responses).Problem object

The quote object

FieldDescription
IDid · string · requiredPattern ^quo_[0-9A-HJKMNP-TV-Z]{26}$.
Productproduct · string · requiredtelegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium.
Selectionselection · Selection object · required
Quantityselection.quantity · integer
Monthsselection.months · integer
Recipientrecipient · Recipient object · requiredQuote responses only. The display name is never stored on orders or sent in webhooks.
Telegram usernamerecipient.telegram_username · string · required
Display namerecipient.display_name · string or null · required
Foundrecipient.found · boolean · requiredThe provider found an account at the username. Not a verification of who owns it. Always true.
Recipient lookuprecipient_lookup · string or nullThe recipient lookup this quote was bound to, or null.
Amountamount · Money object · required
Amountamount.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencyamount.currency · string · requiredUSD. One of USD.
Settlementsettlement · object, one of 2Either shape 1: currency, asset, amount_nanogram, amount_gram, price_usd_micros, price_book_version, rounding, rate; or shape 2: currency, amount_usd_micros, amount_usd, price_usd_micros, price_book_version.
Pricing versionpricing_version · string · required
Price basisprice_basis · objectUSD quotes: how this price was set and when a new quote could differ.
Kindprice_basis.kind · stringOne of usd_fixed, usd_cost_plus.
Currencyprice_basis.currency · stringOne of USD.
Updatesprice_basis.updates · stringThe same, in words, for a person.
Reprice threshold bpsprice_basis.reprice_threshold_bps · integerusd_cost_plus only: the cost move, in basis points, that changes a price. At least 1.
Quote valid secondsprice_basis.quote_valid_seconds · integerAt least 0.
Quantitiesprice_basis.quantities · array of objectusd_cost_plus on the price list only: the whole quantities each product is priced for. A quantity in range is quoted with POST /v1/quotes.
Productprice_basis.quantities[].product · stringtelegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium.
Minprice_basis.quantities[].min · integerAt least 1.
Maxprice_basis.quantities[].max · integerAt least 1.
Expires atexpires_at · string · requiredFormat date-time.
Created atcreated_at · string · requiredFormat date-time.
Breakdownbreakdown · QuoteBreakdown objectWhat the quote is made of, restating figures the server already priced: nothing here is computed for display. total is exactly what an order from this quote holds from the balance. Charges are not itemised and no balance after the order is projected here: the server computes neither at quote time (the order's reservation is the real balance after it).
Pricebreakdown.price · Money object
Amountbreakdown.price.amount · integerUSD, in cents. 0 to 100000000000.
Currencybreakdown.price.currency · stringUSD. One of USD.
Asset equivalentbreakdown.asset_equivalent · object, one of 2For an organisation that still spends GRAM, the price as GRAM at the quote's rate (its settlement). Otherwise null. Either shape 1: ; or shape 2: asset, amount_nanogram, amount_gram, rate.
Totalbreakdown.total · object
Currencybreakdown.total.currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD.
Amount minorbreakdown.total.amount_minor · stringPattern ^[1-9][0-9]{0,30}$.
Linesbreakdown.lines · array of BreakdownLineUSD organisations: each line of the total, computed once by the server; they sum to total_usd_micros.
Kindbreakdown.lines[].kind · stringnetwork_fee is paid by Nasfam and is 0. One of product, service_fee, network_fee.
Amount usd microsbreakdown.lines[].amount_usd_micros · stringAn integer number of micro-dollars (1 USD = 1,000,000), as a string. Every price is a whole number of cents. Pattern ^(0|[1-9][0-9]{0,15})$.
Total usd microsbreakdown.total_usd_micros · stringAn integer number of micro-dollars (1 USD = 1,000,000), as a string. Every price is a whole number of cents. Pattern ^(0|[1-9][0-9]{0,15})$.
Paymentpayment · QuotePayment objectWhat the order will charge from the USD balance, fixed by the quote. The projection is the balance at quote time less the amount; the order's reservation gives the real balance after. A negative projection means the order would be refused for insufficient funds.
Pay withpayment.pay_with · stringWhat was asked. One of auto, usd.
Balancepayment.balance · stringOne of usd.
Currencypayment.currency · stringMicro-dollars. One of USD.
Amount minorpayment.amount_minor · stringPattern ^[1-9][0-9]{0,18}$.
Balance before minorpayment.balance_before_minor · stringPattern ^(0|[1-9][0-9]{0,18})$.
Balance after projected minorpayment.balance_after_projected_minor · stringPattern ^-?(0|[1-9][0-9]{0,18})$.
Projectedpayment.projected · booleanOne of true.

Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).

Every kind of response
201 CreatedSynthetic sandbox data
{  "id": "quo_01K7SAMP000000000000000001",  "product": "telegram_stars",  "selection": {    "quantity": 50,    "months": 3  },  "recipient": {    "telegram_username": "nasfam_test_ok",    "display_name": null,    "found": true  },  "recipient_lookup": null,  "amount": {    "amount": 750,    "currency": "USD"  },  "settlement": {    "currency": "USD",    "amount_usd": "7.500000",    "amount_usd_micros": "7500000",    "price_usd_micros": "7500000",    "price_book_version": 1  },  "pricing_version": "sandbox-v1",  "price_basis": {    "kind": "usd_fixed",    "currency": "USD",    "updates": "string",    "reprice_threshold_bps": 1,    "quote_valid_seconds": 0,    "quantities": [      {        "product": "telegram_stars",        "min": 1,        "max": 1000      }    ]  },  "expires_at": "2026-10-10T10:05:02Z",  "created_at": "2026-10-10T10:05:02Z",  "breakdown": {    "price": {      "amount": 750,      "currency": "USD"    },    "asset_equivalent": null,    "total": {      "currency": "USD",      "amount_minor": "7500000"    },    "lines": [      {        "kind": "product",        "amount_usd_micros": "7500000"      }    ],    "total_usd_micros": "7500000"  },  "payment": {    "pay_with": "auto",    "balance": "usd",    "currency": "USD",    "amount_minor": "7500000",    "balance_before_minor": "25000000",    "balance_after_projected_minor": "17500000",    "projected": true  }}
Code for Responses
Response
JSON
201 CreatedSynthetic sandbox data
{  "id": "quo_01K7SAMP000000000000000091",  "product": "telegram_stars",  "selection": {    "quantity": 50  },  "recipient": {    "telegram_username": "nasfam_test_ok",    "display_name": "Sandbox user @nasfam_test_ok",    "found": true  },  "amount": {    "amount": 75,    "currency": "USD"  },  "pricing_version": "sandbox-synthetic-v1",  "settlement": {    "currency": "USD",    "amount_usd_micros": "750000",    "amount_usd": "0.750000",    "price_usd_micros": "750000",    "price_book_version": 1  },  "expires_at": "2026-10-10T10:16:20.000Z",  "created_at": "2026-10-10T10:15:20.000Z",  "recipient_lookup": "rlk_01K7SAMP000000000000000090"}
Expired
JSON
409 ConflictSynthetic sandbox data
{  "type": "about:blank",  "title": "Recipient lookup expired",  "status": 409,  "code": "lookup_expired",  "category": "validation",  "detail": "This recipient lookup has expired. Look the recipient up again.",  "param": "/recipient_lookup",  "request_id": "req_01K7SAMP000000000000000091"}
Changed
JSON
409 ConflictSynthetic sandbox data
{  "type": "about:blank",  "title": "Recipient does not match the lookup",  "status": 409,  "code": "recipient_mismatch",  "category": "validation",  "detail": "The Telegram account at this username changed since the lookup. Look the recipient up again and confirm it.",  "param": "/recipient_lookup",  "request_id": "req_01K7SAMP000000000000000091"}
Error
JSON
429 Too Many RequestsSynthetic sandbox data
{  "type": "about:blank",  "title": "Too many requests",  "status": 429,  "code": "rate_limited",  "category": "rate_limit",  "detail": "Too many requests. Retry after the time in Retry-After.",  "param": null,  "request_id": "req_01K7SAMP000000000000000090"}

How it behaves

What to expect
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyOptional. Sent, it is bound permanently to what the first request made, and a retry repeats nothing.
In the sandboxA nasfam_test_ username chooses what its order will do; nasfam_test_missing is refused with recipient_not_found. See Sandbox scenarios.
On LiveEvery nasfam_test_ username is refused with recipient_not_eligible. The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. A quote reserves nothing, and your balance need not cover it yet.
Status changesNone. It holds a price for up to 60 seconds, and an order can use it once.
Webhook eventsNone.

For telegram_stars: 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. GET /products holds the bounds in force.

Error responses

This operation can also answer with recipient_not_found, recipient_not_eligible, product_unavailable, pricing_unavailable, lookup_expired, recipient_mismatch, idempotency_key_reused, payload_too_large, unknown_field.

Any request can answer with invalid_request, invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, rate_limited, service_unavailable, internal_error. Errors says what to do about each one.