Sandbox scenarios
What you can make the sandbox do, what only it decides, and where the money is in each case.
Sandbox: test money only. No request moves real money.
The sandbox lets you cause some outcomes yourself and decides others for you. This page says which is which, so you never wait for a case that will not come.
For each scenario you get the cause, what to expect, where the money is, and the events that follow. Every order also raises order.accepted, and a failed one order.refunded with its order.failed. Money here is synthetic.
What you can cause, and what you cannot
A telegram_username in the reserved nasfam_test_ namespace chooses what the simulated provider does, on the sandbox host only. Live refuses every one of them. Any other username behaves as an ordinary order.
Money arrives
- Cause. Press Add test funds on Balance in your dashboard.
- Expect. The funding appears in
GET /fundings. Read itsstatus:creditedmeans the money is on the balance. - Money. In
availableonce the funding iscredited, and on the statement as afunding_creditthat names thefunding_id. Apendingfunding is counted inpending_fundinguntil then. - Events. One
funding.creditedevent when the funding is credited.
{ "data": [ { "id": "fnd_ 01K7SAMP000000000000000090", "amount": { "amount": 10000, "currency": "USD" }, "status": "credited", "payer_ name_ masked": null, "received_ at": "2026-10-10T10:14:00.000Z", "credited_ at": "2026-10-10T10:14:00.000Z" } ], "has_ more": false, "next_ cursor": null}An order is accepted
- Cause. Create a quote, then order from it before its
expires_atwith a newIdempotency-Key. - Expect. A 202 with the order:
statusisprocessingandversionis 1. - Money. Moved from
availabletoheldbefore the response was sent. The statement shows anorder_reservethat names theorder_id. - Events. An
order.processingevent.
Create an order from a quote
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process. env. IDEMPOTENCY_ KEY;if ( !idempotencyKey) throw new Error( 'Set IDEMPOTENCY_ KEY once for this purchase ( a new UUID) and keep it for every retry');try { const { status, data: order } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ orders', { quote_ id: 'quo_ 01K7SAMP000000000000000090', reference: 'TEST-0001', }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, 'Idempotency-Key': idempotencyKey, }, }, ); console. log( status, order);} 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})`);}{ "data": [ { "id": "btx_ 01K7SAMP000000000000000091", "type": "order_ reserve", "amount": { "amount": -75, "currency": "USD" }, "available_ after": { "amount": 9925, "currency": "USD" }, "order_ id": "ord_ 01K7SAMP000000000000000090", "funding_ id": null, "created_ at": "2026-10-10T10:15:02.000Z" }, { "id": "btx_ 01K7SAMP000000000000000090", "type": "funding_ credit", "amount": { "amount": 10000, "currency": "USD" }, "available_ after": { "amount": 10000, "currency": "USD" }, "order_ id": null, "funding_ id": "fnd_ 01K7SAMP000000000000000090", "created_ at": "2026-10-10T10:14:00.000Z" } ], "has_ more": false, "next_ cursor": null}A duplicate is prevented
- Cause. Send the same
POST /ordersagain: the same body and the sameIdempotency-Key. The same works forPOST /.sandbox/ funding/ deposits - Expect. A 200 with the header
Idempotent-Replayed: trueand the order as it is now. No second order exists. - Money. Unchanged. One order holds one amount, however many times you send the request.
- Events. Nothing new: the replay creates no order.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": "quo_ 01K7SAMP000000000000000090", "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z"}An unknown outcome: the response never reached you
- Cause. Give your HTTP client a timeout too short to read the answer to
POST /orders, or drop the connection after sending. - Expect. You do not know whether an order exists. Send the same request with the same key: you get the order, as a 202 if the first attempt never arrived or as a 200 replay if it did.
idempotency_in_progressmeans the first attempt is still running: wait and send it again. - Money. Held at most once. Read
GET /balanceor look the order up by yourreferenceif you need to know before you retry. - Events. One
order.processingevent for the one order.
// npm install axiosimport axios from 'axios';try { const { status, data: orders } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ orders', { params: { reference: 'TEST-0001', limit: 10 }, headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, orders);} 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})`);}A successful order
- Cause. Quote and order with the
telegram_usernamenasfam_test_ok. A test event also shows your endpoint the event it raises. - Expect.
statusbecomessucceeded,completed_atis set andversionrises by one. - Money. Captured.
heldfalls by the amount and the statement shows anorder_capture. - Events. An
order.succeededevent with the whole order indata.object.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z"}A failed order
- Cause. Quote and order with the
telegram_usernamenasfam_test_rejected. A test event also shows your endpoint the event it raises. - Expect.
statusbecomesfailedandstatus_reasonsays why. Nothing was delivered. - Money. Released. The amount returns from
heldtoavailableand the statement shows anorder_release. - Events. An
order.failedevent.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "failed", "status_ reason": "recipient_ not_ eligible", "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z"}A delayed order
- Cause. Quote and order with the
telegram_usernamenasfam_test_slow. A test event also shows your endpoint the event it raises. - Expect. The order stays
processing.estimated_completion_at, when present, is an estimate and may pass. That is not a failure. - Money. Still
held. It is neither spent nor free. - Events. Nothing until the state changes. Keep following the order, and never create a second one for the same purchase.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "processing", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 1, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:02.000Z", "completed_ at": null}An unknown outcome: the order is under review
- Cause. Quote and order with the
telegram_usernamenasfam_test_timeout. A test event also shows your endpoint the event it raises. - Expect.
statusbecomesunder_review. The outcome is being checked; it is neither a success nor a failure yet. - Money. Still
heldfor as long as the order is under review. - Events. An
order.under_reviewevent. A later change of state raises its own event.
{ "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "processing", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 1, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:02.000Z", "completed_ at": null}Test recipients
Use one of these as the telegram_username of a lookup, a quote or an order, for Telegram Stars or Telegram Premium. Each chooses what the simulated provider does, through the real ledger and order states. The list is the contract's own.
| Username | What happens |
|---|---|
nasfam_test_ok | Succeeds. Any ordinary username behaves the same. |
nasfam_test_slow | Processing for about 2 minutes, then succeeds. |
nasfam_test_slow_rejected | Processing for about 2 minutes, then a verified failure; the hold is released once. |
nasfam_test_rejected | A verified failure at once; the hold is released once. |
nasfam_test_lost_ack | The provider's answer is lost; a lookup finds the delivery, which is captured once. Never sent twice. |
nasfam_test_timeout | The request never reaches the provider (UNKNOWN). Under review after 30 minutes, money held until two staff decide. |
nasfam_test_unknown | Under review after 30 minutes, then a late success at about 35 minutes, captured once. |
nasfam_test_conflict | Every provider answer names another recipient. Under review at once, money held until two staff decide. |
nasfam_test_missing | The recipient check finds nobody. The quote, or a direct order, is refused and nothing is reserved. |
A request is refused
A refusal answers with a problem document instead of an order, so there is no order and no hold to find. You can cause each of these with the operations you already use. The triggers follow the name of each code.
| To get | Do this |
|---|---|
unknown_field | Add a field the operation does not take. |
invalid_request | Send a quantity of 0, or months of 5. |
idempotency_key_reused | Send a different body with a key you already used. |
quote_expired | Order from a quote after its expires_at. |
quote_already_used | Order from one quote twice, with two keys. |
duplicate_reference | Create two orders with the same reference, with two keys. |
insufficient_funds | Order more than available. |
not_found | Fetch an order with an id that does not exist. |
{ "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"}Test what you cannot force
The contract gives no way to make an order fail, wait or go under review on demand. You can still prove your code handles each case, because the contract fixes the shape of every one of them.
- Send a test event of
order.failed,order.under_reviewororder.succeededto your endpoint. It is signed and delivered like a real one; its order has the all-zero id, so fetching it is 404 and nothing is released. See Testing webhooks. - Take the failed order on this page and pass it to your own code in a test. Do the same for a delivered one.
- Build the other cases from the same order: set
statustounder_revieworprocessing, and raiseversion. - Assert on the money rule for each status: held while
processingorunder_review, captured onsucceeded, released onfailed.
{ "id": "evt_ 0000000000K7SAMP0000000090", "type": "order. succeeded", "timestamp": "2026-10-10T10:13:00.000Z", "environment": "sandbox", "api_ version": "v1", "data": { "object": { "id": "ord_ 00000000000000000000000000", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z" } }, "test": true}Related guides
- Testing webhooks: deliveries, a failure on purpose, and replay.
- Orders and statuses: each status and where the money is.
- Errors: every code, its cause and how to recover.
- Create a Sandbox API key: the host and the key.
