Quotes
Check a recipient and hold a price for up to 60 seconds, before any money moves.
Sandbox: test money only. No request moves real money.
A quote answers two questions before you spend anything: can this recipient receive this product, and what will it cost? It moves no money and reserves nothing.
Availability: Available. Live and verified in production.
Create a quote
Send the product, the telegram_username and the selection: quantity for telegram_stars, months for telegram_premium. The username may carry a leading @; the server normalises it. GET /products holds the bounds in force.
Cite the recipient lookup your customer confirmed as recipient_lookup. Without one, the quote checks the recipient itself.
// 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})`);}Read the answer
recipient: the username as normalised,found, and adisplay_name, on the quote only.foundsays an account exists at the username, never who owns it. The name is never stored on the order or sent in a webhook.amount: the product line before any service fee, in the minor unit of itscurrency. Showsettlementinstead.settlement: what an order from this quote charges, the price to show: USD on USD credits, or, when the workspace pays with GRAM, the GRAM amount with the reference rate and its time.breakdown: what the quote is made of.totalis exactly what an order from it holds.expires_at: when the price stops holding.payment: what an order from this quote will charge from your USD credits.recipient_lookup: the lookup this quote was bound to, or null.
Expiry and single use
An order from a quote charges exactly its settlement. Past expires_at the order is refused with quote_expired, and a second order from it with quote_already_used. Neither reserves anything: quote again.
A quote takes an optional Idempotency-Key. A retry with the same key and request answers 200 with Idempotent-Replayed: true and the same quote, which may have expired since; nothing is priced again.
When a quote is refused
recipient_not_found: nobody has this username. Nothing is reserved.recipient_not_eligible: the recipient cannot receive this product. Everynasfam_test_name is refused this way on Live.pricing_unavailable: no price can be computed now, for example with no fresh reference rate. Try again later.product_unavailable: the product is not orderable right now.lookup_expiredorrecipient_mismatch: the lookup it cites is past its time, or no longer matches. Nothing is held: look the recipient up again.
Related guides
- Orders and statuses: ordering from a quote, or directly with a ceiling.
- Pricing and costs: where a price comes from.
- Recipient lookup: show your customer the account, then quote citing the lookup.
