Get sandbox test run
GET/sandbox/test-runs/{id}
One test run (sandbox host only). The first read with a key passes the run's status_retrieval step.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
Needs orders:read. Another organisation's run is 404 not_found, exactly like an unknown id.
Request
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.
Parameters
| Field | Description |
|---|---|
| IDid · path string · required | Pattern ^itr_[0-9A-HJKMNP-TV-Z]{26}$. |
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ sandbox/ test-runs/ itr_ 01K7SAMP000000000000000001', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, },});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);// npm install axiosimport axios from 'axios';try { const { status, data: run } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ sandbox/ test-runs/ itr_ 01K7SAMP000000000000000090', { 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | The run. 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 |
| 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 test run object
| Field | Description |
|---|---|
| IDid · string · required | Pattern ^itr_[0-9A-HJKMNP-TV-Z]{26}$. |
| Created atcreated_ | Format date-time. |
| Environmentenvironment · string · required | Always sandbox. |
| Started bystarted_ | One of key, member. |
| Key IDkey_ | Pattern ^[a-z2-7]{16}$. |
| 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. |
| Scenarioscenario · string · required | What 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 · required | waiting: the status read or the webhook delivery has not happened yet. One of completed, waiting. |
| Outcomeoutcome · string · required | The simulated order's outcome. Never a real order. One of succeeded, failed, processing, refused. |
| Simulated order IDsimulated_ | ord_00000000000000000000000000 for an accepted simulation, which no order can have: GET /orders/{id} is 404 for it. Null for a refusal. |
| Webhook endpoint IDwebhook_ | |
| Stepssteps · array of TestRunStep · required | |
| Stepsteps[]. | One of authentication, validation, product_access, order_acceptance, processing, outcome, status_retrieval, webhook_event, webhook_delivery. |
| Basissteps[]. | real: checked against this organisation's records. simulated: the scenario's answer; no order exists. One of real, simulated. |
| Statesteps[]. | One of passed, failed, simulated, checking, not_applicable, skipped. |
| Atsteps[]. | Format date-time. |
| Statussteps[]. | The HTTP status a real createOrder would have answered at this step, where one applies. |
| Codesteps[]. | A problem code (a simulated refusal, or a real product refusal), or a webhook failure class. |
| Event IDsteps[]. | |
| Delivery IDsteps[]. | |
| Elapsed mselapsed_ | From creation to the last step finished; null while waiting. At least 0. |
| Docs URLdocs_ | Format uri. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "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/ "}{ "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": "completed", "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": "passed", "at": "2026-10-10T10:13:34.000Z", "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": 4000, "docs_ url": "https:// business. example. com/ docs/ testing#test-runs"}{ "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 | Not needed: a GET changes nothing, so it is safe to send again. |
| In the sandbox | Served, on your own test records. |
| On Live | Does not exist: the request answers 404 there. |
| Funding | None. This request does not touch your balance. |
| Status changes | None. |
| Webhook events | None. |
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.
