Webhooks

NexaPay sends signed outbound webhooks to the merchant webhookUrl whenever merchant account events complete.

How Signing Works

NexaPay signs each webhook payload with the merchant’s webhookSecret
Merchants verify the signature before trusting the payload
Signature verification should happen in your backend, not in browser code

Headers

NexaPay includes headers similar to:

x-nexapay-signature
x-nexapay-timestamp
x-nexapay-event
x-nexapay-event-id
x-nexapay-business-id

Signature Scheme

The signature is computed over the raw body plus timestamp using HMAC SHA-256.

Webhook Events

`deposit.received`

Sent when money is credited to a merchant virtual account or business account.

{
  "event": "deposit.received",
  "eventId": "evt_01JABC123XYZ",
  "businessId": "66f1234567890abcde123456",
  "businessName": "Acme Stores",
  "environment": "prod",
  "occurredAt": "2026-05-07T10:15:30.000Z",
  "data": {
    "transactionId": "20260507101530abc",
    "reference": "PAY_20260507_001",
    "accountNumber": "9123456789",
    "amount": 50000,
    "senderName": "John Doe",
    "senderAccount": "0123456789",
    "senderBank": "GTBank",
    "balanceAfter": 125000,
    "status": "successful",
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}

`withdrawal.completed`

Sent when a merchant withdrawal settles successfully.

{
  "event": "withdrawal.completed",
  "eventId": "evt_01JWXYZ456ABC",
  "businessId": "66f1234567890abcde123456",
  "businessName": "Acme Stores",
  "environment": "prod",
  "occurredAt": "2026-05-07T12:00:00.000Z",
  "data": {
    "transactionId": "20260507115959xyz",
    "reference": "20260507115959xyz",
    "amount": 100000,
    "fee": 2050,
    "totalDebit": 102050,
    "bankAccount": "0123456789",
    "bankName": "GTBank",
    "providerReference": "090110260507120000123456789012",
    "status": "successful",
    "metadata": {
      "purpose": "payout",
      "batchId": "batch_7781"
    }
  }
}

`withdrawal.failed`

Sent when a merchant withdrawal does not complete.

{
  "event": "withdrawal.failed",
  "eventId": "evt_01JWXYZ789DEF",
  "businessId": "66f1234567890abcde123456",
  "businessName": "Acme Stores",
  "environment": "prod",
  "occurredAt": "2026-05-07T12:05:00.000Z",
  "data": {
    "transactionId": "20260507120459uvw",
    "reference": "20260507120459uvw",
    "amount": 100000,
    "fee": 2050,
    "totalDebit": 102050,
    "bankAccount": "0123456789",
    "bankName": "GTBank",
    "providerReference": null,
    "status": "failed",
    "failureReason": "Insufficient beneficiary balance",
    "metadata": {
      "purpose": "payout",
      "batchId": "batch_7781"
    }
  }
}

`cross_border.collection.success`

Sent when a cross-border collection succeeds and the merchant’s NGN wallet has been credited.

{
  "event": "cross_border.collection.success",
  "eventId": "evt_01K4ABCD1234XYZ",
  "businessId": "69e698368d883f70f4d4ed21",
  "businessName": "Acme Stores",
  "environment": "prod",
  "occurredAt": "2026-09-03T13:10:30.000Z",
  "data": {
    "transactionId": "NexaPay20260903140945570d4ed2170c3",
    "merchantReference": "ORDER-TEST-001",
    "sourceAmount": 100,
    "sourceCurrency": "KES",
    "targetAmount": 953.42,
    "targetCurrency": "NGN",
    "rate": 9.5342,
    "status": "COMPLETED",
    "provider": "brails",
    "providerReference": "0f3cd184-6978-4696-9ef8-50d552b7c342"
  }
}

`cross_border.collection.failed`

Sent when a cross-border collection fails before the merchant wallet is credited.

`cross_border.collection.review`

Sent when provider confirmation does not match the expected amount or currency. The collection is held for review and the merchant wallet is not automatically credited.

Merchant Webhook Secret

NexaPay exposes the merchant webhook secret from the dashboard for authenticated users.

Reveal Secret

GET /business/webhook-secret Returns the current webhook secret so the merchant can verify signatures.

Regenerate Secret

POST /business/webhook-secret/regenerate Rotates the secret and returns the new value. Merchants should update their backend immediately after regenerating.

Delivery Rules

Webhooks are sent after the relevant transaction is committed.
Delivery is best-effort with retries.
Merchants should deduplicate using eventId.
Merchants should verify the signature before processing the payload.

Getting Started

Business Account

Payments Collection

Virtual Accounts

Cross-Border Collections

Crypto Collections

Payouts & Withdrawals

Bill Payments

Transactions

Notifications

Webhooks

Webhooks

How Signing Works

Headers

Signature Scheme

Webhook Events

`deposit.received`

`withdrawal.completed`

`withdrawal.failed`

`cross_border.collection.success`

`cross_border.collection.failed`

`cross_border.collection.review`

Merchant Webhook Secret

Reveal Secret

Regenerate Secret

Delivery Rules

​Webhooks

​How Signing Works

​Headers

​Signature Scheme

​Webhook Events

​deposit.received

​withdrawal.completed

​withdrawal.failed

​cross_border.collection.success

​cross_border.collection.failed

​cross_border.collection.review

​Merchant Webhook Secret

​Reveal Secret

​Regenerate Secret

​Delivery Rules

Webhooks

How Signing Works

Headers

Signature Scheme

Webhook Events

`deposit.received`

`withdrawal.completed`

`withdrawal.failed`

`cross_border.collection.success`

`cross_border.collection.failed`

`cross_border.collection.review`

Merchant Webhook Secret

Reveal Secret

Regenerate Secret

Delivery Rules