Skip to content

Verify order status

An order finishes after the response. Read its final state, receive the event, and retry without creating a second order.

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

In this step you follow the order your code sent to a final state, two ways: by reading it, and by receiving an event. You also learn the one rule for a retry.

An order is asynchronous. The 202 you received says the order was accepted and its amount held. It does not say the order was delivered: only succeeded says that. A request handed to a provider, or a transaction seen on a network, is not a delivery.

What the first response tells you

  • 202 Accepted. The order exists, its amount is held, and delivery is in progress.
  • 200 with Idempotent-Replayed: true. A replay of a request you already sent. The body is the order as it is now.
  • A problem document. Read code: it tells you whether to fix the request, wait, or stop. Errors has the recovery for each code.
  • A 5xx, or no answer at all. The outcome is unknown, never failed. Send the same request with the same key.

Follow the order to a final state

Fetch the order until status leaves processing. estimated_completion_at, when present, is an estimate from the queue, never a promise.

StatusYour moneyWhat to do
ProcessingprocessingHeld. Delivery is in progress.Wait for the next state.
SucceededsucceededCaptured. The order is paid for.Nothing. completed_at is set.
FailedfailedReleased back to available.Read status_reason; order again if it makes sense.
Under reviewunder_reviewYour funds stay held.No action needed.

Each state change increases version by one. When two signals disagree, the higher version is the newer truth, whatever the timestamps say.

Code for Follow the order to a final state
GET /v1/orders/{id}Sandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: order } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/orders/ord_01K7SAMP000000000000000090',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  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})`);}

Receive the event

Polling works, but an event is how you are told. Register an HTTPS endpoint for order.succeeded, order.failed and order.under_review; Webhooks shows the request. Each event is sent to your URL with the whole order in data.object.

The handler in the example does what every receiver must:

  1. Verify the signature over the raw body, and refuse a stale timestamp.
  2. Answer quickly, then do the work.
  3. Record the event id and ignore one you have seen. An event can arrive more than once.
  4. Ignore an event type you do not handle, and act on no test event. New types will be added.
  5. Keep the highest version you have seen for each order and ignore anything lower.

Fetch the order with GET /orders/{id} before you release value to your own customer. Webhooks shows the signature check, and a test event proves it before your first order.

Code for Receive the event
Runs on your server, at the URL you registered
// Node.js 18 or later, no package. NASFAM_WEBHOOK_SECRET is the endpoint's whsec_ secret, read from the environment.import { createHmac, timingSafeEqual } from 'node:crypto';import { createServer } from 'node:http';const secret = Buffer.from(process.env.NASFAM_WEBHOOK_SECRET.slice('whsec_'.length), 'base64'); // the secret's bytes, not its textconst handled = new Set(); // event ids already handled: use your databaseconst versions = new Map(); // the highest version seen per order// Standard Webhooks v1: one signature in the header is the HMAC of this body, and the timestamp is within 5 minutes.function verified(body, headers) {  const header = (name) => String(headers[name] ?? '');  const id = header('webhook-id');  const timestamp = header('webhook-timestamp');  if (!id || !/^[0-9]+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;  const expected = createHmac('sha256', secret).update(`${id}.${timestamp}.`).update(body).digest();  return header('webhook-signature').split(' ').some((signature) => {    const [version, value = ''] = signature.split(',');    const given = Buffer.from(value, 'base64');    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);  });}createServer((req, res) => {  const chunks = [];  req.on('data', (chunk) => chunks.push(chunk));  req.on('end', () => {    // Verify the raw body before you parse it: a body parsed and written again is not what was signed.    const body = Buffer.concat(chunks);    if (!verified(body, req.headers)) {      res.writeHead(400).end();      return;    }    // Answer at once and do the work afterwards: a slow answer is retried.    res.writeHead(200).end();    const event = JSON.parse(body.toString('utf8'));    // A test event is marked and its object is synthetic: acknowledge it and act on nothing.    if (event.test === true) {      console.log('test', event.type, event.id);      return;    }    // Retries and replays carry the same webhook-id, so the same event can arrive twice.    if (handled.has(event.id)) return;    handled.add(event.id);    // Ignore a type you do not handle: new ones will be added.    if (!event.type.startsWith('order.')) return;    // Order events are ordered by version, never by timestamp.    const order = event.data.object;    if (order.version <= (versions.get(order.id) ?? 0)) return;    versions.set(order.id, order.version);    // Fetch the order with GET /orders/{id} before you release value to your customer.    console.log(event.type, order.id, order.status);  });}).listen(Number(process.env.PORT ?? 3000));

Retry without a second order

  • Your request timed out. Send it again with the same Idempotency-Key. If you lost the key, look the order up by your reference before you do anything else.
  • An event was not received. A failed attempt is retried, and any delivery can be replayed. The event is also in GET /events for 30 days; see Webhooks.
  • An event arrived twice. That is expected. Your record of event ids makes the second one a no-op.

What you should see

The order leaves processing. In the examples it is delivered: status is succeeded, version is 2 and completed_at is set. Your endpoint receives the matching order.succeeded event with the same order inside.

A nasfam_test_ recipient chooses the outcome; see Sandbox scenarios. Write your code for all four statuses.

Code for What you should see
The event your endpoint receives
JSON
order.succeededSynthetic sandbox data
{  "id": "evt_01K7SAMP000000000000000090",  "type": "order.succeeded",  "timestamp": "2026-10-10T10:15:05.000Z",  "environment": "sandbox",  "api_version": "v1",  "data": {    "object": {      "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"    }  }}

If it fails

What you seeWhat to check
The order stays processingThat is not a failure. Keep following it, and do not create another order for the same purchase.
status is failedRead status_reason; Orders and statuses lists the values. The held amount is back in available.
status is under_reviewThe outcome is being checked and your funds stay held. Show it as pending. Never order again to find out.
Your endpoint received nothingRead the endpoint: enabled may be false, with a disabled_reason. Then list its deliveries; Webhooks shows how. A test event checks the endpoint without an order.
Your endpoint refuses every deliveryThe signature check fails. Verify the raw body, not a parsed one, with the bytes of your endpoint's secret. Send a test event to try again.
not_foundNo order has this id. Check you kept the id from the 202.
idempotency_in_progressThe first attempt is still running. Wait a moment and send the same request again.

Next step

Sandbox step 7 of 7: Continue to Live. What the Sandbox must show before Live opens, how you move across, and what stays behind.