Skip to content

List sandbox test runs

GET/sandbox/test-runs

The organisation's test runs, newest first (sandbox host only). Kept 30 days.

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.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required

No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.

Parameters

FieldDescription
Limitlimit · query integer1 to 100. Default 20.
Cursorcursor · query stringUp to 256 characters.
The request in cURL, JavaScript and Python
GET /v1/sandbox/test-runsSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/sandbox/test-runs', {  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);
Code for Request
GET /v1/sandbox/test-runsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: runs } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/sandbox/test-runs',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, runs);} 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
OK200Test runs. 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. ).TestRunList 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 list object

FieldDescription
Has morehas_more · boolean · required
Next cursornext_cursor · string or null · required
Datadata · array of TestRun · required
IDdata[].id · string · requiredPattern ^itr_[0-9A-HJKMNP-TV-Z]{26}$.
Created atdata[].created_at · string · requiredFormat date-time.
Environmentdata[].environment · string · requiredAlways sandbox.
Started bydata[].started_by · string · requiredOne of key, member.
Key IDdata[].key_id · string or null · requiredPattern ^[a-z2-7]{16}$.
Productdata[].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.
Scenariodata[].scenario · 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.
Statedata[].state · string · requiredwaiting: the status read or the webhook delivery has not happened yet. One of completed, waiting.
Outcomedata[].outcome · string · requiredThe simulated order's outcome. Never a real order. One of succeeded, failed, processing, refused.
Simulated order IDdata[].simulated_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 IDdata[].webhook_endpoint_id · string or null · required
Stepsdata[].steps · array of TestRunStep · required
Stepdata[].steps[].step · string · requiredOne of authentication, validation, product_access, order_acceptance, processing, outcome, status_retrieval, webhook_event, webhook_delivery.
Basisdata[].steps[].basis · string · requiredreal: checked against this organisation's records. simulated: the scenario's answer; no order exists. One of real, simulated.
Statedata[].steps[].state · string · requiredOne of passed, failed, simulated, checking, not_applicable, skipped.
Atdata[].steps[].at · string or null · requiredFormat date-time.
Statusdata[].steps[].status · integer or nullThe HTTP status a real createOrder would have answered at this step, where one applies.
Codedata[].steps[].code · string or nullA problem code (a simulated refusal, or a real product refusal), or a webhook failure class.
Event IDdata[].steps[].event_id · string
Delivery IDdata[].steps[].delivery_id · string
Elapsed msdata[].elapsed_ms · integer or null · requiredFrom creation to the last step finished; null while waiting. At least 0.
Docs URLdata[].docs_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
200 OKSynthetic sandbox data
{  "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/"    }  ],  "has_more": false,  "next_cursor": null}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "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": "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"    }  ],  "has_more": false,  "next_cursor": null}
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.
IdempotencyNot needed: a GET changes nothing, so it is safe to send again.
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.