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
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
Content-Type | application/json | Required |
Idempotency-Key | 3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0d | Optional |
Parameters
| Field | Description |
|---|---|
| Idempotency keyIdempotency-Key · header string | Bound 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
| Field | Description |
|---|---|
| Productproduct · string · required | Always telegram_stars. |
| Telegram usernametelegram_ | Normalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$. |
| Quantityquantity · integer · required | Bounded 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_ | Pattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$. |
| Pay withpay_ | A USD organisation always pays in USD; both values mean that. One of auto, usd. |
product is telegram_premium
| Field | Description |
|---|---|
| Productproduct · string · required | Always telegram_premium. |
| Telegram usernametelegram_ | Normalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$. |
| Monthsmonths · integer · required | One of 3, 6, 12. |
| Recipient lookuprecipient_ | Pattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$. |
| Pay withpay_ | A USD organisation always pays in USD; both values mean that. One of auto, usd. |
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);Quote the confirmed recipient
// 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
// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | A 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 |
| Created201 | Quote 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 large413 | The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id. | Problem object |
| Too many requests429 | Too 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 statusdefault | Error (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
| Field | Description |
|---|---|
| IDid · string · required | Pattern ^quo_[0-9A-HJKMNP-TV-Z]{26}$. |
| Productproduct · string · required | telegram_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. | |
| Monthsselection. | |
| Recipientrecipient · Recipient object · required | Quote responses only. The display name is never stored on orders or sent in webhooks. |
| Telegram usernamerecipient. | |
| Display namerecipient. | |
| Foundrecipient. | The provider found an account at the username. Not a verification of who owns it. Always true. |
| Recipient lookuprecipient_ | The recipient lookup this quote was bound to, or null. |
| Amountamount · Money object · required | |
| Amountamount. | USD, in cents. 0 to 100000000000. |
| Currencyamount. | USD. One of USD. |
| Settlementsettlement · object, one of 2 | Either 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_ | |
| Price basisprice_ | USD quotes: how this price was set and when a new quote could differ. |
| Kindprice_ | One of usd_fixed, usd_cost_plus. |
| Currencyprice_ | One of USD. |
| Updatesprice_ | The same, in words, for a person. |
| Reprice threshold bpsprice_ | usd_cost_plus only: the cost move, in basis points, that changes a price. At least 1. |
| Quote valid secondsprice_ | At least 0. |
| Quantitiesprice_ | usd_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_ | telegram_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_ | At least 1. |
| Maxprice_ | At least 1. |
| Expires atexpires_ | Format date-time. |
| Created atcreated_ | Format date-time. |
| Breakdownbreakdown · QuoteBreakdown object | What 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. | |
| Amountbreakdown. | USD, in cents. 0 to 100000000000. |
| Currencybreakdown. | USD. One of USD. |
| Asset equivalentbreakdown. | For 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. | |
| Currencybreakdown. | USD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD. |
| Amount minorbreakdown. | Pattern ^[1-9][0-9]{0,30}$. |
| Linesbreakdown. | USD organisations: each line of the total, computed once by the server; they sum to total_usd_micros. |
| Kindbreakdown. | network_fee is paid by Nasfam and is 0. One of product, service_fee, network_fee. |
| Amount usd microsbreakdown. | An 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. | An 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 object | What 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. | What was asked. One of auto, usd. |
| Balancepayment. | One of usd. |
| Currencypayment. | Micro-dollars. One of USD. |
| Amount minorpayment. | Pattern ^[1-9][0-9]{0,18}$. |
| Balance before minorpayment. | Pattern ^(0|[1-9][0-9]{0,18})$. |
| Balance after projected minorpayment. | Pattern ^-?(0|[1-9][0-9]{0,18})$. |
| Projectedpayment. | One of true. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "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 }}{ "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"}{ "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"}{ "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"}{ "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 | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Optional. Sent, it is bound permanently to what the first request made, and a retry repeats nothing. |
| In the sandbox | A nasfam_test_ username chooses what its order will do; nasfam_test_missing is refused with recipient_not_found. See Sandbox scenarios. |
| On Live | Every 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. |
| Funding | None. A quote reserves nothing, and your balance need not cover it yet. |
| Status changes | None. It holds a price for up to 60 seconds, and an order can use it once. |
| Webhook events | None. |
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.
