Skip to content

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 its status: credited means the money is on the balance.
  • Money. In available once the funding is credited, and on the statement as a funding_credit that names the funding_id. A pending funding is counted in pending_funding until then.
  • Events. One funding.credited event when the funding is credited.
Code for Money arrives
The funding on the list
JSON
200 OKSynthetic sandbox data
{  "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_at with a new Idempotency-Key.
  • Expect. A 202 with the order: status is processing and version is 1.
  • Money. Moved from available to held before the response was sent. The statement shows an order_reserve that names the order_id.
  • Events. An order.processing event.
Code for An order is accepted

Create an order from a quote

POST /v1/ordersSandbox, test key
// 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})`);}
The statement: the reserve, above the credit
JSON
200 OKSynthetic sandbox data
{  "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 /orders again: the same body and the same Idempotency-Key. The same works for POST /sandbox/funding/deposits.
  • Expect. A 200 with the header Idempotent-Replayed: true and 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.
Code for A duplicate is prevented
The answer to the second request
JSON
200 OKSynthetic sandbox data
{  "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_progress means the first attempt is still running: wait and send it again.
  • Money. Held at most once. Read GET /balance or look the order up by your reference if you need to know before you retry.
  • Events. One order.processing event for the one order.
Code for An unknown outcome: the response never reached you
GET /v1/ordersSandbox, test key
// 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_username nasfam_test_ok. A test event also shows your endpoint the event it raises.
  • Expect. status becomes succeeded, completed_at is set and version rises by one.
  • Money. Captured. held falls by the amount and the statement shows an order_capture.
  • Events. An order.succeeded event with the whole order in data.object.
Code for A successful order
A delivered order
JSON
200 OKSynthetic sandbox data
{  "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_username nasfam_test_rejected. A test event also shows your endpoint the event it raises.
  • Expect. status becomes failed and status_reason says why. Nothing was delivered.
  • Money. Released. The amount returns from held to available and the statement shows an order_release.
  • Events. An order.failed event.
Code for A failed order
A failed order
JSON
200 OKSynthetic sandbox data
{  "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_username nasfam_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.
Code for A delayed order
An order still in progress
JSON
202 AcceptedSynthetic sandbox data
{  "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_username nasfam_test_timeout. A test event also shows your endpoint the event it raises.
  • Expect. status becomes under_review. The outcome is being checked; it is neither a success nor a failure yet.
  • Money. Still held for as long as the order is under review.
  • Events. An order.under_review event. A later change of state raises its own event.
Code for An unknown outcome: the order is under review
The order, before it goes under review
JSON
202 AcceptedSynthetic sandbox data
{  "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.

UsernameWhat happens
nasfam_test_okSucceeds. Any ordinary username behaves the same.
nasfam_test_slowProcessing for about 2 minutes, then succeeds.
nasfam_test_slow_rejectedProcessing for about 2 minutes, then a verified failure; the hold is released once.
nasfam_test_rejectedA verified failure at once; the hold is released once.
nasfam_test_lost_ackThe provider's answer is lost; a lookup finds the delivery, which is captured once. Never sent twice.
nasfam_test_timeoutThe request never reaches the provider (UNKNOWN). Under review after 30 minutes, money held until two staff decide.
nasfam_test_unknownUnder review after 30 minutes, then a late success at about 35 minutes, captured once.
nasfam_test_conflictEvery provider answer names another recipient. Under review at once, money held until two staff decide.
nasfam_test_missingThe 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 getDo this
unknown_fieldAdd a field the operation does not take.
invalid_requestSend a quantity of 0, or months of 5.
idempotency_key_reusedSend a different body with a key you already used.
quote_expiredOrder from a quote after its expires_at.
quote_already_usedOrder from one quote twice, with two keys.
duplicate_referenceCreate two orders with the same reference, with two keys.
insufficient_fundsOrder more than available.
not_foundFetch an order with an id that does not exist.
Code for A request is refused
What a refusal looks like
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"}

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_review or order.succeeded to 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 status to under_review or processing, and raise version.
  • Assert on the money rule for each status: held while processing or under_review, captured on succeeded, released on failed.
Code for Test what you cannot force
A test event
JSON
order.succeededSynthetic sandbox data
{  "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}