> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Events

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

## Security

See [Webhooks Introduction](/api-reference/endpoint/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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/api-reference/models#failure-reasons) for the full code list.

```json theme={null}
{
  "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.