{
"id": "8f14e45f-ceea-4e7a-9f1d-6b1c2a3d4e5f",
"event": "TRANSACTION.CREATED",
"createdAt": "2026-04-24T09:13:33.883Z",
"data": {
"status": "PENDING",
"type": "WITHDRAW",
"channel": "BANK_ACCOUNT",
"sourceAmount": "3.316587998",
"sourceCurrency": "USD",
"destinationAmount": "5000",
"destinationCurrency": "NGN",
"destinationId": "695271a3ba52c13b669fad2b",
"customerId": "69528240ba52c13b669fb239",
"transactionId": "6952826eba52c13b669fb263",
"meta": {
"narration": ""
},
"createdAt": "2025-12-29T13:30:22.554Z",
"updatedAt": "2025-12-29T13:30:22.554Z"
}
}Transaction Events
Afriex sends real-time webhook notifications to your configured URL whenever a transaction is created or updated.
TRANSACTION.CREATED: Fired when a new transaction is initiated.TRANSACTION.UPDATED: Fired when the transaction status or other fields change (most commonlystatusandupdatedAt).
The payload structure is identical for both events. Only the event field and potentially status + updatedAt differ.
Security: Every request includes an x-webhook-signature header and an x-afriex-business-id header carrying your business id. You must verify this signature using Afriex’s public key before processing. The key is an elliptic-curve (secp384r1 / P-384) key, not RSA. The signature is ECDSA with SHA-256, DER-encoded and then base64-encoded, computed over the exact raw request body, so verify it before parsing or re-serialising the JSON. See the Webhooks Overview & Security section for verification instructions.
{
"id": "8f14e45f-ceea-4e7a-9f1d-6b1c2a3d4e5f",
"event": "TRANSACTION.CREATED",
"createdAt": "2026-04-24T09:13:33.883Z",
"data": {
"status": "PENDING",
"type": "WITHDRAW",
"channel": "BANK_ACCOUNT",
"sourceAmount": "3.316587998",
"sourceCurrency": "USD",
"destinationAmount": "5000",
"destinationCurrency": "NGN",
"destinationId": "695271a3ba52c13b669fad2b",
"customerId": "69528240ba52c13b669fb239",
"transactionId": "6952826eba52c13b669fb263",
"meta": {
"narration": ""
},
"createdAt": "2025-12-29T13:30:22.554Z",
"updatedAt": "2025-12-29T13:30:22.554Z"
}
}Sample Payloads
Transaction Created
{
"id": "e9ec2c1e-902b-5d2d-8659-e1529afd23ab",
"event": "TRANSACTION.CREATED",
"createdAt": "2026-04-24T09:13:33.883Z",
"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
{
"id": "2708d455-5789-5229-b606-f4fab67648cf",
"event": "TRANSACTION.UPDATED",
"createdAt": "2026-04-24T09:15:45.123Z",
"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
Whenstatus 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.
{
"id": "d374dc7f-9a8c-52f4-8e71-09ee46d0dddf",
"event": "TRANSACTION.UPDATED",
"createdAt": "2026-04-24T09:17:02.410Z",
"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"
}
}
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.Body
Unique ID of this event. Every delivery attempt of the same event carries the same id, so use it to ignore a delivery you have already processed.
"8f14e45f-ceea-4e7a-9f1d-6b1c2a3d4e5f"
Identifies which transaction event occurred
TRANSACTION.CREATED, TRANSACTION.UPDATED "TRANSACTION.UPDATED"
When Afriex created the event. Retries keep this value, and the signature covers it, so you can reject a delivery that is older than you expect.
"2026-04-24T09:13:33.883Z"
Details of the transaction
Show child attributes
Show child attributes
Response
Acknowledge receipt. Return any 2xx status code quickly. Response body is ignored.