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.
| Status | Your money | What to do |
|---|---|---|
| Processingprocessing | Held. Delivery is in progress. | Wait for the next state. |
| Succeededsucceeded | Captured. The order is paid for. | Nothing. completed_at is set. |
| Failedfailed | Released back to available. | Read status_reason; order again if it makes sense. |
| Under reviewunder_ | Your 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.
// 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:
- Verify the signature over the raw body, and refuse a stale timestamp.
- Answer quickly, then do the work.
- Record the event
idand ignore one you have seen. An event can arrive more than once. - Ignore an event type you do not handle, and act on no test event. New types will be added.
- Keep the highest
versionyou 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.
// 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 yourreferencebefore 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 /eventsfor 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.
{ "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 see | What to check |
|---|---|
The order stays processing | That is not a failure. Keep following it, and do not create another order for the same purchase. |
status is failed | Read status_reason; Orders and statuses lists the values. The held amount is back in available. |
status is under_review | The outcome is being checked and your funds stay held. Show it as pending. Never order again to find out. |
| Your endpoint received nothing | Read 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 delivery | The 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_found | No order has this id. Check you kept the id from the 202. |
idempotency_in_progress | The 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.
Related concepts
- Orders and statuses: each status and each reason an order fails.
- Webhooks: endpoints, events, deliveries and replay.
- Testing webhooks: a failure on purpose, a repeat and a replay.
- Sandbox scenarios: which outcomes you can cause.
- Idempotency and safe retries: what to retry, and how.
