Transaction Events - Afriex Business API

Security

See Webhooks Introduction for setup, signature validation, and retry behavior.

Event Types

• TRANSACTION.CREATED - A new transaction has been initiated
• TRANSACTION.UPDATED - Transaction status or fields have changed

Sample Payloads

Transaction Created

{
  "event": "TRANSACTION.CREATED",
  "data": {
    "status": "PENDING",
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "sourceAmount": "5000",
    "sourceCurrency": "NGN",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "destinationId": "68e676bac48ad6beae3559a0",
    "customerId": "68e6717848e1f632e9686460",
    "transactionId": "69eb343d4973a18671813fb3",
    "merchantReference": "myReference",
    "meta": {
      "reference": "myReference",
      "idempotencyKey": "myReference",
      "narration": "My first transaction"
    },
    "createdAt": "2026-04-24T09:13:33.883Z",
    "updatedAt": "2026-04-24T09:13:33.883Z"
  }
}

Transaction Updated

{
  "event": "TRANSACTION.UPDATED",
  "data": {
    "status": "PENDING",
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "sourceAmount": "5000",
    "sourceCurrency": "NGN",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "destinationId": "68e676bac48ad6beae3559a0",
    "customerId": "68e6717848e1f632e9686460",
    "transactionId": "69eb343d4973a18671813fb3",
    "merchantReference": "myReference",
    "meta": {
      "reference": "myReference",
      "idempotencyKey": "myReference",
      "narration": "My first transaction"
    },
    "createdAt": "2026-04-24T09:13:33.883Z",
    "updatedAt": "2026-04-24T09:15:45.123Z"
  }
}

Transaction Failed

When status transitions to FAILED or REJECTED, the payload’s meta.failureReason describes why using a stable AFX_* code and a customer-safe message. See Failure reasons for the full code list.

{
  "event": "TRANSACTION.UPDATED",
  "data": {
    "status": "FAILED",
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "sourceAmount": "5000",
    "sourceCurrency": "NGN",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "destinationId": "68e676bac48ad6beae3559a0",
    "customerId": "68e6717848e1f632e9686460",
    "transactionId": "69eb343d4973a18671813fb3",
    "merchantReference": "myReference",
    "meta": {
      "reference": "myReference",
      "idempotencyKey": "myReference",
      "narration": "My first transaction",
      "failureReason": {
        "code": "AFX_VELOCITY_LIMIT_EXCEEDED",
        "message": "This transaction exceeds the allowed velocity limit. Try again later.",
        "retryable": true
      }
    },
    "createdAt": "2026-04-24T09:13:33.883Z",
    "updatedAt": "2026-04-24T09:17:02.410Z"
  }
}

The event field will be TRANSACTION.CREATED or TRANSACTION.UPDATED depending on the action that triggered the notification.

Response

Return 200 (or another 2xx) after successful validation and processing.