Transaction Events

Afriex sends real-time webhook notifications to your configured URL whenever a transaction is created or updated.

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. Cross-currency transactions also carry a rate field alongside the amounts, holding the realized source-to-destination exchange rate. See Transaction for the full field list.

TRANSACTION.UPDATED is not a terminal-status-only signal. It fires on every status change Afriex considers worth reporting, including intermediate ones such as PROCESSING and CUSTOMER_ACTION_REQUIRED, so a single transaction can produce several. Always branch on the payload’s status field rather than treating any delivery as final.

Response

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

Overview

Core Concepts

Balance

Checkout Sessions

Rates

Customers

Payment Methods

Transactions

Webhooks

Media

SME Registration

Security

Event Types

Sample Payloads

Transaction Created

Transaction Updated

Transaction Failed

Response

​Security

​Event Types

​Sample Payloads

​Transaction Created

​Transaction Updated

​Transaction Failed

​Response

Security

Event Types

Sample Payloads

Transaction Created

Transaction Updated

Transaction Failed

Response