event field in the webhook payload.
Payment & Transaction Events
| Event | Description | Typical Trigger |
|---|---|---|
transaction.pending | Payment initialized and awaiting customer action | Initialize Payment |
transaction.success | Payment completed successfully | Customer finishes checkout or transfer hits reserved account |
transaction.failed | Payment failed or was declined | Bank decline, authentication failure, or timeout |
Transfer Events
| Event | Description | Typical Trigger |
|---|---|---|
transfer.pending | Transfer created and awaiting bank processing | Initiate Transfer |
transfer.success | Funds delivered to the recipient | Receiving bank confirms settlement |
transfer.failed | Transfer rejected or reversed by partner bank | Invalid recipient, insufficient funds, or compliance hold |
transfer.reversed | Previously successful transfer has been reversed | Manual reversal or partner clawback |
Recipient Events
| Event | Description | Typical Trigger |
|---|---|---|
recipient.created | Recipient passed compliance checks and is ready for transfers | Create Recipient |
recipient.verification_failed | Recipient verification failed | Invalid bank details or KYC mismatch |
Virtual Account Events
| Event | Description | Typical Trigger |
|---|---|---|
reserved_account.credit | Customer transfer received into a virtual account | Incoming bank transfer to STATIC or DYNAMIC account |
reserved_account.debit | Funds moved out of a reserved account | Merchant withdrawals or automated sweeps |
reserved_account.low_balance | Available balance dropped below configured threshold | Balance monitoring alert |
Wallet & Card Events
| Event | Description | Typical Trigger |
|---|---|---|
wallet.created | Wallet successfully provisioned | Create Wallet |
wallet.activated | Wallet verified and active for transactions | KYC checks completed |
card.issued | Virtual card created for a wallet | Debit card feature enabled during wallet creation |
account.opened | Bank account number allocated to the wallet | NGN wallets with virtual account support |
Identity Verification Events
| Event | Description | Typical Trigger |
|---|---|---|
verification.bvn.completed | BVN verification finished (success or failure) | BVN Verification |
verification.bvn.match_found | BVN matched a customer record | Identity match at required confidence |
verification.bvn.watchlist_hit | BVN found on a compliance watch list | Sanctions or blacklist match |
Event Handling Checklist
- Log the
event,transaction.reference, and timestamp for auditing. - Queue long-running operations to avoid response timeouts.
- Provide manual replay tooling so operations teams can reprocess specific events.
- Monitor for event bursts—throttle downstream systems as needed.