Skip to content

Create statement

POST/statements

Request an account statement for whole local days.

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

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

Needs statements:read. from and to are local dates in the workspace's finance zone, to excluded and at most the current day, at most 366 days. The server prepares the statement once the period is complete and reconciles it before any file exists: opening plus every movement must equal the closing recomputed from the ledger, or it fails with reconciliation_failed. CSV always, PDF only where the server offers it. The files are downloaded from the dashboard. Amounts are micro-dollars (1 USD = 1,000,000) as integer strings, and exact dollars to six decimals in the CSV. A retry with the same Idempotency-Key answers the same statement.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired
Idempotency-Key3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0dRequired

Parameters

FieldDescription
Idempotency keyIdempotency-Key · header string · requiredBound permanently to the operation it created (an order, a simulated funding). Reuse it on every retry of the same request. Pattern ^[A-Za-z0-9_-]{16,64}$.

Body

Unknown fields are rejected.

FieldDescription
Fromfrom · string · requiredFormat date.
Toto · string · requiredFormat date.
Formatsformats · array of stringAt least 1 item. No duplicates. Each one of csv, pdf.
The request in cURL, JavaScript and Python
POST /v1/statementsSandbox, test keyIdempotency-Key required
// 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');const response = await fetch('https://sandbox-api.nasfampay.com/v1/statements', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',    'Idempotency-Key': idempotencyKey,  },  body: JSON.stringify({ from: '2026-10-10', to: '2026-10-10' }),});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/statementsSandbox, 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: statement } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/statements',    {      from: '2026-10-01',      to: '2026-10-10',      formats: ['csv'],    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, statement);} 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
OK200Replay of an earlier request with the same Idempotency-Key. 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.Statement object
Accepted202The statement, queued. 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. ).Statement 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 statement object

FieldDescription
IDid · string · requiredPattern ^stm_[0-9A-HJKMNP-TV-Z]{26}$.
Statestate · string · requiredOne of queued, ready, failed.
Failure codefailure_code · string or null · requiredOne of reconciliation_failed, too_large, null.
Currencycurrency · string · requiredOne of USD.
Timezonetimezone · string · required
Reconciledreconciled · boolean · required
Periodperiod · object · required
Fromperiod.from · string · requiredFormat date.
Toperiod.to · string · requiredFormat date.
From atperiod.from_at · string · requiredFormat date-time.
To atperiod.to_at · string · requiredFormat date-time.
Formatsformats · array of string · requiredEach one of csv, pdf.
Movement countmovement_count · integer or null · requiredAt least 0.
Created atcreated_at · string · requiredFormat date-time.
Finished atfinished_at · string or null · requiredFormat date-time.
Filesfiles · array of object · required
Formatfiles[].format · string · requiredOne of csv, pdf.
Byte sizefiles[].byte_size · integer · requiredAt least 1.
Sha256files[].sha256 · string · requiredPattern ^[0-9a-f]{64}$.
Expires atfiles[].expires_at · string · requiredFormat date-time.
Availablefiles[].available · boolean · required
Summarysummary · object, one of 2 · requiredEither shape 1: ; or shape 2: opening, closing, categories, spent, orders_charged, deposits_credited, reservations_returned, refunded, adjustments, spent_by_product.

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
202 AcceptedSynthetic sandbox data
{  "id": "stm_01K7SAMP000000000000000001",  "state": "queued",  "failure_code": null,  "currency": "USD",  "timezone": "string",  "reconciled": true,  "period": {    "from": "2026-10-10",    "to": "2026-10-10",    "from_at": "2026-10-10T10:05:02Z",    "to_at": "2026-10-10T10:05:02Z"  },  "formats": [    "csv"  ],  "movement_count": null,  "created_at": "2026-10-10T10:05:02Z",  "finished_at": null,  "files": [    {      "format": "csv",      "byte_size": 1,      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",      "expires_at": "2026-10-10T10:05:02Z",      "available": true    }  ],  "summary": null}

Not finished. Only a final status means it is done: read it again or wait for its webhook. An outcome that is not known yet is held, never a failure.

Code for Responses
Response
JSON
202 AcceptedSynthetic sandbox data
{  "id": "stm_01K7SAMP000000000000000090",  "state": "queued",  "failure_code": null,  "currency": "USD",  "timezone": "Africa/Lagos",  "reconciled": false,  "period": {    "from": "2026-10-01",    "to": "2026-10-10",    "from_at": "2026-09-30T23:00:00.000Z",    "to_at": "2026-10-09T23:00:00.000Z"  },  "formats": [    "csv"  ],  "movement_count": null,  "created_at": "2026-10-10T10:20:00.000Z",  "finished_at": null,  "files": [],  "summary": 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.
IdempotencyRequired, and bound permanently to what the first request made. Reuse it on every retry: a retry answers with the same operation, never a second one.
In the sandboxServed, on your own test records.
On LiveThe same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
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.