Webhooks - Axra

Webhooks let Axra push payment events to your server the moment they happen, so you never need to poll the API to check whether a payment succeeded. When a payment event occurs — a charge completes, a dispute opens, or funds settle — Axra sends an HTTP POST request to the webhookUrl you configured in your business profile. Because many payment flows (like 3DS redirects or card network clearing) are asynchronous, you should always confirm payment status through webhooks rather than relying solely on the response from a charge request.

Configure your webhook URL

Set your webhook endpoint in the Axra dashboard under Settings → Business Profile, or update it programmatically:

PUT /business/config

{
  "webhookUrl": "https://your-domain.com/webhooks/axra"
}

Your webhook URL must be publicly reachable. During local development, use a tool like ngrok to expose your local server.

Event types

Axra delivers the following events to your webhook endpoint:

Event	Description
`payment.created`	A payment record was created (before capture).
`payment.completed`	Payment captured successfully.
`payment.failed`	Payment processing failed.
`payment.settled`	Funds cleared and available for withdrawal.
`payment.refunded`	Payment has been refunded.
`payment.disputed`	A dispute (chargeback) has been opened.
`payment.dispute_won`	Dispute resolved in your favor.
`payment.dispute_lost`	Dispute resolved against you.
`payment_link.session.completed`	A hosted checkout session completed successfully.
`collection.created`	A local-rails collection was created.
`collection.processing`	Funds have been detected, settlement is in progress.
`collection.completed`	Funds settled; merchant USDC wallet credited.
`collection.failed`	Collection failed (e.g. amount mismatch, provider rejection).
`collection.expired`	Virtual account expired without payment.
`payout.initiated`	A payout was accepted and the merchant wallet debited (status `CREATED`).
`payout.submitted`	The payout was dispatched to the payout provider (status `SUBMITTED`).
`payout.settled`	Funds were delivered to the recipient (status `SETTLED`).
`payout.failed`	The payout failed; the wallet debit was reversed (status `FAILED`).
`payout.cancelled`	A `CREATED` payout was cancelled before dispatch (status `CANCELLED`).
`payout.review`	The payout is held for compliance/admin review (status `PENDING_REVIEW`).
`invoice.created`	An invoice was issued.
`invoice.paid`	An invoice was paid.
`recurring_gift.charge.succeeded`	A recurring-gift schedule successfully charged.
`recurring_gift.charge.failed`	A recurring-gift charge attempt failed.

Webhook payload structure

Every webhook request shares the same envelope format:

{
  "event": "payment.completed",
  "timestamp": "2026-03-20T14:30:05.000Z",
  "data": { ... }
}

The data object varies by event type. Below are the payloads for each event.

payment.created

Fires when a payment record is created — before the funds are captured. Useful for pre-populating order rows in your system.

{
  "paymentId": "bpay_01H...",
  "amount": 49.99,
  "currency": "USD",
  "status": "PENDING"
}

payment.completed

Fires when a payment is captured successfully. Update your order status to reflect payment received.

{
  "paymentId": "bpay_01H...",
  "amount": "49.99",
  "currency": "USD"
}

payment.failed

Fires when payment processing fails. The reason field contains the failure code.

{
  "paymentId": "bpay_01H...",
  "reason": "card_declined"
}

payment.settled

Fires when funds have cleared the card networks and are credited to your merchant wallet (minus fees).

{
  "paymentId": "bpay_01H...",
  "amount": "49.99",
  "currency": "USD",
  "settledAt": "2026-03-22T10:00:00.000Z"
}

payment.refunded

Fires when a refund is issued for a payment.

{
  "paymentId": "bpay_01H...",
  "amount": 49.99,
  "currency": "USD",
  "refundId": "re_1Abc..."
}

payment.disputed

Fires when a cardholder opens a dispute (chargeback). The full charge amount is debited from your account immediately, plus a non-refundable dispute fee.

{
  "paymentId": "bpay_01H...",
  "disputeId": "dp_1Abc...",
  "disputeAmount": 49.99,
  "disputeFee": 5.82,
  "reason": "fraudulent"
}

payment.dispute_won / payment.dispute_lost

Fires when a dispute is resolved. If you win, the charge amount is re-credited to your account (the dispute fee is not refunded). If you lose, no further changes occur — the funds were already debited.

{
  "paymentId": "bpay_01H...",
  "won": true,
  "chargeAmount": 49.99
}

collection.created

Fires immediately after a collection is created through the direct API or hosted checkout. data.object mirrors GET /business/collections/{id}.

{
  "livemode": true,
  "object": {
    "id": "lcoll_01HVXYZ123456",
    "object": "collection",
    "status": "pending",
    "amount": 10000,
    "currency": "ngn",
    "country": "NG",
    "expiresAt": "2026-05-11T12:34:56Z",
    "channel": {
      "rail": "bank",
      "provider": "PAGA",
      "channelId": "ch_01HVNG7BANK"
    },
    "instructions": {
      "kind": "bank_transfer",
      "bankName": "Indulge MFB",
      "accountNumber": "9906154084",
      "accountName": "AXRA / Your Business",
      "reference": null
    },
    "metadata": { "orderId": "ord_1042" },
    "businessPaymentId": "bp_01HVXYZ123456",
    "source": "api",
    "createdAt": "2026-05-11T12:24:56Z"
  }
}

collection.processing

Fires when inbound funds are detected and settlement is in progress.

{
  "livemode": true,
  "object": {
    "id": "lcoll_01HVXYZ789012",
    "object": "collection",
    "status": "processing",
    "amount": 5000,
    "currency": "kes",
    "country": "KE",
    "expiresAt": "2026-05-11T12:44:56Z",
    "channel": {
      "rail": "momo",
      "provider": "M-PESA",
      "channelId": "ch_01HVKE7MOMO"
    },
    "instructions": {
      "kind": "momo_prompt",
      "phone": "+254712345678",
      "prompt": "Approve the payment prompt from your mobile money provider."
    },
    "metadata": null,
    "businessPaymentId": "bp_01HVXYZ789012",
    "source": "api",
    "createdAt": "2026-05-11T12:34:56Z"
  }
}

collection.completed

Fires when the collection settles and your USDC wallet is credited. Fulfill the order on this event.

{
  "livemode": true,
  "object": {
    "id": "lcoll_01HVXYZ345678",
    "object": "collection",
    "status": "completed",
    "amount": 2500,
    "currency": "zar",
    "country": "ZA",
    "expiresAt": "2026-05-11T12:49:56Z",
    "channel": {
      "rail": "eft",
      "provider": "Ozow",
      "channelId": "ch_01HVZA7EFT"
    },
    "instructions": {
      "kind": "hosted_page",
      "url": "https://pay.ozow.com/...",
      "provider": "Ozow"
    },
    "metadata": { "orderId": "ord_2048" },
    "businessPaymentId": "bp_01HVXYZ345678",
    "source": "session",
    "createdAt": "2026-05-11T12:39:56Z"
  }
}

collection.failed

Fires when the provider reports a terminal failure (for example, amount mismatch or rejection).

{
  "livemode": true,
  "object": {
    "id": "lcoll_01HVXYZ901234",
    "object": "collection",
    "status": "failed",
    "amount": 10000,
    "currency": "ngn",
    "country": "NG",
    "expiresAt": "2026-05-11T12:34:56Z",
    "channel": {
      "rail": "bank",
      "provider": "PAGA",
      "channelId": "ch_01HVNG7BANK"
    },
    "instructions": {
      "kind": "bank_transfer",
      "bankName": "Indulge MFB",
      "accountNumber": "9906154084",
      "accountName": "AXRA / Your Business",
      "reference": null
    },
    "metadata": null,
    "businessPaymentId": "bp_01HVXYZ901234",
    "source": "api",
    "createdAt": "2026-05-11T12:24:56Z"
  }
}

collection.expired

Fires when deposit instructions expire before payment arrives.

{
  "livemode": true,
  "object": {
    "id": "lcoll_01HVXYZ567890",
    "object": "collection",
    "status": "expired",
    "amount": 5000,
    "currency": "kes",
    "country": "KE",
    "expiresAt": "2026-05-11T12:44:56Z",
    "channel": {
      "rail": "momo",
      "provider": "M-PESA",
      "channelId": "ch_01HVKE7MOMO"
    },
    "instructions": {
      "kind": "momo_prompt",
      "phone": "+254712345678",
      "prompt": "Approve the payment prompt from your mobile money provider."
    },
    "metadata": null,
    "businessPaymentId": "bp_01HVXYZ567890",
    "source": "session",
    "createdAt": "2026-05-11T12:34:56Z"
  }
}

payment_link.session.completed

Fires when a hosted checkout / payment-link session is completed. source identifies the originator (payment_link, invoice, etc.) and sourceId is the originating resource ID.

{
  "sessionId": "cs_01H...",
  "source": "payment_link",
  "sourceId": "plink_01H...",
  "status": "COMPLETED",
  "amount": 4999,
  "currency": "USD"
}

invoice.created

Fires when a new invoice is issued.

{
  "invoiceId": "inv_01H...",
  "invoiceNumber": "INV-0001",
  "status": "DRAFT",
  "totalAmount": 5000,
  "currency": "USD"
}

invoice.paid

Fires when an invoice is paid via its checkout session.

{
  "invoiceId": "inv_01H...",
  "invoiceNumber": "INV-0001",
  "sessionId": "cs_01H..."
}

recurring_gift.charge.succeeded

Fires when a recurring-gift schedule successfully captures a charge. chargeCount is the cumulative number of successful charges on this schedule.

{
  "recurringGiftId": "rg_01H...",
  "paymentLinkId": "plink_01H...",
  "amount": 5000,
  "currency": "USD",
  "chargeCount": 3,
  "paymentIntentId": "pi_01H..."
}

recurring_gift.charge.failed

Fires when a recurring-gift charge attempt fails. failureCount tracks consecutive failures; the schedule is paused after the configured retry limit.

{
  "recurringGiftId": "rg_01H...",
  "paymentLinkId": "plink_01H...",
  "error": "card_declined",
  "failureCount": 1
}

payout.* (initiated / submitted / settled / failed / cancelled / review)

Fires across the payout lifecycle for outbound local-rail payouts. data.object is the same shape as GET /v1/business/payouts/{id}. Fulfill or reconcile your records on payout.settled; reverse on payout.failed.

{
  "object": {
    "id": "po_01H...",
    "status": "SETTLED",
    "rail": "LOCAL_BANK",
    "amount": "100.00",
    "currency": "USDC",
    "recipientId": "rec_01H...",
    "destinationMasked": { "country": "NG", "accountNumber": "••••6789", "bankName": "Example Bank" },
    "providerRef": "yc_01H...",
    "settledAt": "2026-06-02T10:00:30.000Z",
    "quote": { "dstAmount": "151000", "rate": "1510", "axraFee": "0.50", "currency": "NGN", "country": "NG" }
  },
  "livemode": true
}

Webhook request headers

Axra includes these headers on every webhook request:

Header	Description
`Content-Type`	`application/json`
`X-Axra-Signature`	HMAC-SHA256 signature of the raw request body
`X-Axra-Event`	The event type (e.g., `payment.completed`)

Signature verification

Always verify the X-Axra-Signature header before processing a webhook. Without verification, any party can send requests to your endpoint and trigger side effects in your system.

To verify a webhook:

Get your webhook secret

Find your webhookSecret in the Axra dashboard under Settings → API Keys. Store it as an environment variable — never hardcode it.

Compute the expected signature

Compute an HMAC-SHA256 digest of the raw request body (the bytes as received, before any JSON parsing) using your webhookSecret as the key.

Compare using constant-time equality

Compare the computed digest to the value in the X-Axra-Signature header using a constant-time comparison function. This prevents timing attacks.

Reject if signatures do not match

Return a 401 Unauthorized response immediately. Do not process the event.

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, webhookSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex'),
  );
}

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-axra-signature'];
  const rawBody = JSON.stringify(req.body);

  if (!verifyWebhookSignature(rawBody, signature, process.env.AXRA_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'payment.completed':
      // Update your order status
      break;
    case 'payment.settled':
      // Funds are now available
      break;
    case 'payment.disputed':
      // Alert your fraud team
      break;
  }

  res.status(200).send('OK');
});

Use the raw request body bytes for signature computation — not a re-serialized version of the parsed JSON. JSON serialization is not guaranteed to be deterministic, and any whitespace difference will cause verification to fail.

Retry policy

Axra considers a delivery successful when your endpoint responds with an HTTP 2xx status code within 30 seconds. If delivery fails, Axra retries with the following schedule:

Attempt	Delay after failure
1	Immediate
2	30 seconds
3	60 seconds
4	90 seconds
5	120 seconds

After 5 failed attempts, the webhook delivery is marked permanently failed. You can review failed deliveries and trigger manual redelivery in the Axra dashboard → Webhooks → Delivery Logs.

Best practices

Return 200 quickly — acknowledge receipt immediately, then process the event in a background job. Long-running handlers risk timeouts and unnecessary retries.
Handle duplicates — network retries mean your endpoint may receive the same event more than once. Use paymentId as an idempotency key to ensure you process each event exactly once.
Always verify signatures — reject any request where X-Axra-Signature does not match your computed value.
Use HTTPS in production — plain HTTP webhook URLs are rejected for live-mode credentials.
Use ngrok during local development — run ngrok http 3000 to get a public URL that tunnels to your local server.

​Configure your webhook URL

​Event types

​Webhook payload structure

​Webhook request headers

​Signature verification

​Retry policy

​Best practices

Configure your webhook URL

Event types

Webhook payload structure

Webhook request headers

Signature verification

Retry policy

Best practices