Skip to content

Monitor orders and webhooks

Register your Live webhook endpoint, follow every order to its end, and reconcile the money each day.

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

In this step you set up what you watch once real orders flow: a Live webhook endpoint, the statuses that need you, and a daily check that the money adds up.

Register your Live endpoint

Your Sandbox endpoint stays in the Sandbox. Register your Live endpoint on the Live host, for order.succeeded, order.failed and order.under_review. Its secret is shown once: store it on your server, apart from your Sandbox secret, and check every webhook-signature with it; see Verifying a delivery.

Then send it a test event, so you know the signature check works before a real order needs it. Webhooks shows how.

Code for Register your Live endpoint
POST /v1/webhook-endpointsLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: endpoint } = await axios.post(    'https://api.nasfampay.com/v1/webhook-endpoints',    {      url: 'https://example.com/webhooks/nasfam',      events: [        'order.succeeded',        'order.failed',        'order.under_review',        'funding.credited',      ],      description: 'Order updates',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, endpoint);} 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})`);}

Handle every event

  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.

Answer within 15 seconds, then do the work. A failed attempt is retried, and an endpoint that keeps failing is disabled. Every event is also in GET /events for 30 days, so you can catch up after downtime.

Watch the statuses that need you

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.

Read GET /orders/{id} before you release value to your customer. under_review keeps the money held while the outcome is confirmed: show it as pending, and never order again to find out.

Code for Watch the statuses that need you
GET /v1/orders/{id}Live, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: order } = await axios.get(    'https://api.nasfampay.com/v1/orders/ord_01K7SAMP000000000000000090',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_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})`);}

Reconcile each day

  • Every accepted order has an order_reserve on GET /balance/transactions, naming its order_id.
  • Every succeeded order has an order_capture, and every failed one an order_release back to available.
  • An order still processing or under_review has its reserve and nothing else yet.
  • Your own records name the same orders, by your reference.

A difference is a question for the order, never a reason to order again. Your dashboard's Orders and request logs show the same records.

Code for Reconcile each day
GET /v1/balance/transactionsLive, real money
// npm install axiosimport axios from 'axios';try {  const { status, data: transactions } = await axios.get(    'https://api.nasfampay.com/v1/balance/transactions',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_LIVE_KEY}`,      },    },  );  console.log(status, transactions);} 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})`);}

What you should see

Your Live endpoint is registered and has passed a test event. Each order ends succeeded or failed, and the statement shows its reserve and then its capture or release. The order you read reads like this:

Code for What you should see
A delivered Live order
JSON
200 OKSynthetic sandbox data
{  "id": "ord_01K7SAMP000000000000000091",  "environment": "live",  "status": "succeeded",  "status_reason": null,  "product": "telegram_stars",  "selection": {    "quantity": 50  },  "recipient": {    "telegram_username": "customer"  },  "amount": {    "amount": 75,    "currency": "USD"  },  "quote_id": "quo_01K7SAMP000000000000000091",  "pricing_version": "example",  "reference": "TEST-0002",  "version": 2,  "estimated_completion_at": "2026-10-10T10:15:35.000Z",  "created_at": "2026-10-10T10:15:30.000Z",  "updated_at": "2026-10-10T10:15:05.000Z",  "completed_at": "2026-10-10T10:15:05.000Z",  "recipient_lookup": "rlk_01K7SAMP000000000000000090"}

If it fails

What you seeWhat to check
Your endpoint received nothingRead the endpoint: enabled may be false, with a disabled_reason. Then list its deliveries; Webhooks shows how.
Your endpoint refuses every deliveryIt is checking with your Sandbox secret. Use the Live endpoint's own secret, over the raw body.
An order stays under_reviewThat is not a failure. The money stays held until the outcome is confirmed. Never order again.
The statement and your records disagreeFind the order by your reference with GET /orders?reference=, and read its status before you change anything.
key_environment_mismatchA Sandbox key reached the Live host. Use your Live key.
rate_limitedWait the seconds in Retry-After. Read less often: an event tells you when an order changes.

Next step

This is the last step. Keep the Sandbox for testing changes before they reach Live: Sandbox scenarios lists what you can test, and the guides go deeper on each part, starting with Authentication and keys.