Skip to content

Create sandbox test run

POST/sandbox/test-runs

Run a simulated order through the integration steps (sandbox host only; 404 in production). Writes no order and moves no money.

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

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

Needs sandbox:write. order is validated exactly as createOrder validates its body, so a malformed order is refused 400 as an order would be, and no run is made. The key, the contract and the product's availability are checked for real; acceptance, processing and the outcome are the scenario's, simulated, against the order id ord_00000000000000000000000000, which no order can have. No balance, statement, order list, provider or chain is touched. With webhook_endpoint_id, one test event of the outcome's type ("test": true, synthetic object) is signed and delivered to that endpoint as any event is, and the run shows its real answer. Read the run back with this key (getSandboxTestRun) to pass its status-retrieval step. At most 60 runs an hour per organisation; the webhook part also spends the endpoint's 20 test events an hour.

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

Unknown fields are rejected.

FieldDescription
Scenarioscenario · string · requiredWhat the simulated order does. An invalid request is tested by sending one: it is refused 400 as createOrder would refuse it, and no run is made. One of succeeded, provider_delay, fulfilment_failed, insufficient_funds, recipient_not_found, recipient_not_eligible.
Orderorder · OrderDirect object · required
Productorder.product · 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.
Telegram usernameorder.telegram_username · string · requiredNormalised server-side (leading @ or t.me/ removed, lower-cased). Pattern ^@?[A-Za-z0-9_]{5,32}$.
Quantityorder.quantity · integerBounded 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.
Monthsorder.months · integerOne of 3, 6, 12.
Max amountorder.max_amount · Money object · required
Amountorder.max_amount.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencyorder.max_amount.currency · string · requiredUSD. One of USD.
Recipient lookuporder.recipient_lookup · objectThe lookup your customer confirmed. The order's own quote is bound to it and refused as a quote citing it is. Part of the request an Idempotency-Key binds.
Referenceorder.reference · stringPattern ^[A-Za-z0-9._:-]{1,64}$. Up to 64 characters.
Metadataorder.metadata · Metadata objectUp to 20 keys.
Webhook endpoint IDwebhook_endpoint_id · stringPattern ^whe_[0-9A-HJKMNP-TV-Z]{26}$.
The request in cURL, JavaScript and Python
POST /v1/sandbox/test-runsSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/sandbox/test-runs', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    scenario: 'succeeded',    order: {      product: 'telegram_stars',      telegram_username: 'nasfam_test_ok',      max_amount: { amount: 750, currency: 'USD' },    },  }),});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
POST /v1/sandbox/test-runsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: run } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/sandbox/test-runs',    {      scenario: 'succeeded',      order: {        product: 'telegram_stars',        quantity: 50,        reference: 'TEST-0001',        telegram_username: 'nasfam_test_ok',        max_amount: { amount: 100, currency: 'USD' },      },    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, run);} 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 run it made, as it is now. Nothing is run 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.TestRun object
Created201The run, with every step it could finish now. 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. ).TestRun 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 test run object

FieldDescription
IDid · string · requiredPattern ^itr_[0-9A-HJKMNP-TV-Z]{26}$.
Created atcreated_at · string · requiredFormat date-time.
Environmentenvironment · string · requiredAlways sandbox.
Started bystarted_by · string · requiredOne of key, member.
Key IDkey_id · string or null · requiredPattern ^[a-z2-7]{16}$.
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.
Scenarioscenario · string · requiredWhat the simulated order does. An invalid request is tested by sending one: it is refused 400 as createOrder would refuse it, and no run is made. One of succeeded, provider_delay, fulfilment_failed, insufficient_funds, recipient_not_found, recipient_not_eligible.
Statestate · string · requiredwaiting: the status read or the webhook delivery has not happened yet. One of completed, waiting.
Outcomeoutcome · string · requiredThe simulated order's outcome. Never a real order. One of succeeded, failed, processing, refused.
Simulated order IDsimulated_order_id · string or null · requiredord_00000000000000000000000000 for an accepted simulation, which no order can have: GET /orders/{id} is 404 for it. Null for a refusal.
Webhook endpoint IDwebhook_endpoint_id · string or null · required
Stepssteps · array of TestRunStep · required
Stepsteps[].step · string · requiredOne of authentication, validation, product_access, order_acceptance, processing, outcome, status_retrieval, webhook_event, webhook_delivery.
Basissteps[].basis · string · requiredreal: checked against this organisation's records. simulated: the scenario's answer; no order exists. One of real, simulated.
Statesteps[].state · string · requiredOne of passed, failed, simulated, checking, not_applicable, skipped.
Atsteps[].at · string or null · requiredFormat date-time.
Statussteps[].status · integer or nullThe HTTP status a real createOrder would have answered at this step, where one applies.
Codesteps[].code · string or nullA problem code (a simulated refusal, or a real product refusal), or a webhook failure class.
Event IDsteps[].event_id · string
Delivery IDsteps[].delivery_id · string
Elapsed mselapsed_ms · integer or null · requiredFrom creation to the last step finished; null while waiting. At least 0.
Docs URLdocs_url · string · requiredFormat uri.

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": "itr_01K7SAMP000000000000000001",  "created_at": "2026-10-10T10:05:02Z",  "environment": "sandbox",  "started_by": "key",  "key_id": null,  "product": "telegram_stars",  "scenario": "succeeded",  "state": "completed",  "outcome": "succeeded",  "simulated_order_id": null,  "webhook_endpoint_id": null,  "steps": [    {      "step": "authentication",      "basis": "real",      "state": "passed",      "at": null,      "status": null,      "code": null,      "event_id": "string",      "delivery_id": "string"    }  ],  "elapsed_ms": null,  "docs_url": "https://example.com/"}
Code for Responses
Response
JSON
201 CreatedSynthetic sandbox data
{  "id": "itr_01K7SAMP000000000000000090",  "created_at": "2026-10-10T10:13:30.000Z",  "environment": "sandbox",  "started_by": "key",  "key_id": "sampleidsampleid",  "product": "telegram_stars",  "scenario": "succeeded",  "state": "waiting",  "outcome": "succeeded",  "simulated_order_id": "ord_00000000000000000000000000",  "webhook_endpoint_id": null,  "steps": [    {      "step": "authentication",      "basis": "real",      "state": "passed",      "at": "2026-10-10T10:13:30.000Z",      "status": null,      "code": null    },    {      "step": "validation",      "basis": "real",      "state": "passed",      "at": "2026-10-10T10:13:30.000Z",      "status": null,      "code": null    },    {      "step": "product_access",      "basis": "real",      "state": "passed",      "at": "2026-10-10T10:13:30.000Z",      "status": null,      "code": null    },    {      "step": "order_acceptance",      "basis": "simulated",      "state": "simulated",      "at": "2026-10-10T10:13:30.000Z",      "status": 202,      "code": null    },    {      "step": "processing",      "basis": "simulated",      "state": "simulated",      "at": "2026-10-10T10:13:30.000Z",      "status": null,      "code": null    },    {      "step": "outcome",      "basis": "simulated",      "state": "simulated",      "at": "2026-10-10T10:13:30.000Z",      "status": null,      "code": null    },    {      "step": "status_retrieval",      "basis": "real",      "state": "checking",      "at": null,      "status": null,      "code": null    },    {      "step": "webhook_event",      "basis": "real",      "state": "not_applicable",      "at": null,      "status": null,      "code": null    },    {      "step": "webhook_delivery",      "basis": "real",      "state": "not_applicable",      "at": null,      "status": null,      "code": null    }  ],  "elapsed_ms": null,  "docs_url": "https://business.example.com/docs/testing#test-runs"}
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 sandboxServed, on your own test records.
On LiveDoes not exist: the request answers 404 there.
FundingNone. This request does not touch your balance.
Status changesNone.
Webhook eventsNone.

Error responses

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.