Event Payloads

Detailed payload examples for each event type.

virtual_account.created

{
  "id": "evt_abc123",
  "type": "virtual_account.created",
  "data": {
    "accountId": 12345,
    "accountName": "ESCA/John Doe",
    "accountNumber": "8012345678",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "currency": "NGN",
    "createdAt": "2026-01-18T10:00:00.000Z"
  },
  "createdAt": "2026-01-18T10:00:00.000Z"
}

Field	Type	Description
`accountId`	integer	Unique account identifier
`accountName`	string	Name on the account
`accountNumber`	string	Virtual account number
`bankName`	string	Name of the bank
`bankCode`	string	Bank code
`currency`	string	Account currency (NGN, GHS)
`createdAt`	string	Account creation timestamp

virtual_account.credited

{
  "id": "evt_def456",
  "type": "virtual_account.credited",
  "data": {
    "accountId": 12345,
    "accountNumber": "8012345678",
    "accountName": "ESCA/John Doe",
    "amount": 50000.00,
    "currency": "NGN",
    "reference": "TRF123456789",
    "narration": "Payment from John Doe",
    "sender": "John Doe",
    "senderAccountNumber": "0123456789",
    "balance": 50000.00,
    "creditedAt": "2026-01-18T10:30:00.000Z"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

Field	Type	Description
`accountId`	integer	Account that received the funds
`accountNumber`	string	Virtual account number
`accountName`	string	Name on the account
`amount`	number	Amount credited
`currency`	string	Currency of the deposit
`reference`	string	Bank reference for the transaction
`narration`	string	Payment description/narration
`sender`	string	Name of the sender
`senderAccountNumber`	string	Sender's account number
`balance`	number	New account balance after credit
`creditedAt`	string	Credit timestamp

transfer.initiated

{
  "id": "evt_ghi789",
  "type": "transfer.initiated",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": 12345,
    "amount": 10000.00,
    "currency": "NGN",
    "destinationBankCode": "000007",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JANE SMITH",
    "description": "Payment for services",
    "initiatedAt": "2026-01-18T10:30:00.000Z"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

Field	Type	Description
`uuid`	string	Unique transfer identifier
`accountId`	integer	Source account ID
`amount`	number	Transfer amount
`currency`	string	Transfer currency
`destinationBankCode`	string	Destination bank code
`destinationAccountNumber`	string	Destination account number
`destinationAccountName`	string	Destination account name
`description`	string	Transfer description
`initiatedAt`	string	Transfer initiation timestamp

transfer.completed

{
  "id": "evt_jkl012",
  "type": "transfer.completed",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": 12345,
    "status": "SUCCESS",
    "amount": 10000.00,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JANE SMITH",
    "destinationBankCode": "000007",
    "destinationBankName": "Fidelity Bank Plc",
    "description": "Payment for services",
    "completedAt": "2026-01-18T10:30:05.000Z"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

Field	Type	Description
`uuid`	string	Unique transfer identifier
`accountId`	integer	Source account ID
`status`	string	Transfer status (SUCCESS)
`amount`	number	Transfer amount
`fee`	number	Transfer fee charged
`currency`	string	Transfer currency
`destinationAccountNumber`	string	Destination account number
`destinationAccountName`	string	Destination account name
`destinationBankCode`	string	Destination bank code
`destinationBankName`	string	Destination bank name
`description`	string	Transfer description
`completedAt`	string	Transfer completion timestamp

transfer.failed

{
  "id": "evt_mno345",
  "type": "transfer.failed",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": 12345,
    "status": "FAILED",
    "amount": 10000.00,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JANE SMITH",
    "destinationBankCode": "000007",
    "destinationBankName": "Fidelity Bank Plc",
    "description": "Payment for services",
    "failureReason": "Invalid account number",
    "completedAt": "2026-01-18T10:30:10.000Z"
  },
  "createdAt": "2026-01-18T10:30:10.000Z"
}

Field	Type	Description
`uuid`	string	Unique transfer identifier
`accountId`	integer	Source account ID
`status`	string	Transfer status (FAILED)
`amount`	number	Transfer amount
`fee`	number	Transfer fee (may be refunded)
`currency`	string	Transfer currency
`destinationAccountNumber`	string	Destination account number
`destinationAccountName`	string	Destination account name
`destinationBankCode`	string	Destination bank code
`destinationBankName`	string	Destination bank name
`description`	string	Transfer description
`failureReason`	string	Reason for failure
`completedAt`	string	Failure timestamp

exchange.processing

{
  "id": "evt_exch_abc123",
  "type": "exchange.processing",
  "data": {
    "conversionId": "f7a8b9c0-d1e2-3456-abcd-ef7890123456",
    "sourceCurrency": "NGN",
    "targetCurrency": "USD",
    "sourceAmount": 500000,
    "targetAmount": 312.50,
    "appliedRate": 1600,
    "status": "PROCESSING",
    "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

Field	Type	Description
`conversionId`	string	UUID of the conversion
`sourceCurrency`	string	Source currency
`targetCurrency`	string	Target currency
`sourceAmount`	number	Amount in source currency
`targetAmount`	number	Expected amount in target currency
`appliedRate`	number	Exchange rate applied
`status`	string	Conversion status (PROCESSING)
`quoteId`	string	Quote UUID (only present if a quote was used)

exchange.completed

{
  "id": "evt_exch_def456",
  "type": "exchange.completed",
  "data": {
    "conversionId": "f7a8b9c0-d1e2-3456-abcd-ef7890123456",
    "sourceCurrency": "NGN",
    "targetCurrency": "USD",
    "sourceAmount": 500000,
    "targetAmount": 312.50,
    "appliedRate": 1600,
    "status": "COMPLETED",
    "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

Field	Type	Description
`conversionId`	string	UUID of the conversion
`sourceCurrency`	string	Source currency
`targetCurrency`	string	Target currency
`sourceAmount`	number	Amount debited in source currency
`targetAmount`	number	Amount credited in target currency
`appliedRate`	number	Exchange rate applied
`status`	string	Conversion status (COMPLETED)
`quoteId`	string	Quote UUID (only present if a quote was used)

exchange.failed

{
  "id": "evt_exch_ghi789",
  "type": "exchange.failed",
  "data": {
    "sourceCurrency": "NGN",
    "targetCurrency": "USD",
    "sourceAmount": 500000,
    "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Insufficient balance"
  },
  "createdAt": "2026-01-18T10:30:10.000Z"
}

Field	Type	Description
`sourceCurrency`	string	Source currency
`targetCurrency`	string	Target currency
`sourceAmount`	number	Attempted conversion amount
`quoteId`	string	Quote UUID (only present if a quote was used)
`reason`	string	Reason for failure

bulk_transfer.initiated

{
  "id": "evt_bulk_abc123",
  "type": "bulk_transfer.initiated",
  "data": {
    "batchId": "api-1705574400000-12345",
    "transferCount": 3,
    "transfers": [
      {
        "accountId": 12345,
        "amount": 10000.00,
        "currency": "NGN",
        "destinationBankCode": "058",
        "destinationAccountNumber": "0123456789",
        "destinationAccountName": "JOHN DOE",
        "externalReference": "SAL-001"
      },
      {
        "accountId": 12345,
        "amount": 25000.00,
        "currency": "NGN",
        "destinationBankCode": "044",
        "destinationAccountNumber": "9876543210",
        "destinationAccountName": "JANE SMITH",
        "externalReference": "SAL-002"
      }
    ],
    "initiatedAt": "2026-01-18T10:30:00.000Z"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

Field	Type	Description
`batchId`	string	Unique batch identifier
`transferCount`	integer	Total number of transfers in the batch
`transfers`	array	Array of transfer objects in the batch
`transfers[].accountId`	integer	Source account ID
`transfers[].amount`	number	Transfer amount
`transfers[].currency`	string	Transfer currency
`transfers[].destinationBankCode`	string	Destination bank code
`transfers[].destinationAccountNumber`	string	Destination account number
`transfers[].destinationAccountName`	string	Destination account name
`transfers[].externalReference`	string	Your external reference (if provided)
`initiatedAt`	string	Batch initiation timestamp

bulk_transfer.completed

Fired once per successful transfer within a bulk batch.

{
  "id": "evt_bulk_def456",
  "type": "bulk_transfer.completed",
  "data": {
    "batchId": "api-1705574400000-12345",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": 12345,
    "status": "SUCCESS",
    "amount": 10000.00,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JOHN DOE",
    "destinationBankCode": "058",
    "destinationBankName": "GTBank",
    "description": "Salary payment",
    "completedAt": "2026-01-18T10:30:05.000Z"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

Field	Type	Description
`batchId`	string	Batch this transfer belongs to
`uuid`	string	Unique transfer identifier
`accountId`	integer	Source account ID
`status`	string	Transfer status (SUCCESS)
`amount`	number	Transfer amount
`fee`	number	Transfer fee charged
`currency`	string	Transfer currency
`destinationAccountNumber`	string	Destination account number
`destinationAccountName`	string	Destination account name
`destinationBankCode`	string	Destination bank code
`destinationBankName`	string	Destination bank name
`description`	string	Transfer description
`completedAt`	string	Transfer completion timestamp

bulk_transfer.failed

Fired once per failed transfer within a bulk batch.

{
  "id": "evt_bulk_ghi789",
  "type": "bulk_transfer.failed",
  "data": {
    "batchId": "api-1705574400000-12345",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": 12345,
    "status": "FAILED",
    "amount": 25000.00,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "9876543210",
    "destinationAccountName": "JANE SMITH",
    "destinationBankCode": "044",
    "destinationBankName": "Access Bank",
    "description": "Salary payment",
    "failureReason": "Transfer failed",
    "completedAt": "2026-01-18T10:30:10.000Z"
  },
  "createdAt": "2026-01-18T10:30:10.000Z"
}

Field	Type	Description
`batchId`	string	Batch this transfer belongs to
`uuid`	string	Unique transfer identifier
`accountId`	integer	Source account ID
`status`	string	Transfer status (FAILED)
`amount`	number	Transfer amount
`fee`	number	Transfer fee (may be refunded)
`currency`	string	Transfer currency
`destinationAccountNumber`	string	Destination account number
`destinationAccountName`	string	Destination account name
`destinationBankCode`	string	Destination bank code
`destinationBankName`	string	Destination bank name
`description`	string	Transfer description
`failureReason`	string	Reason for failure
`completedAt`	string	Failure timestamp

payout.initiated

{
  "id": "evt_payout_abc123",
  "type": "payout.initiated",
  "data": {
    "payoutId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "fiat",
    "currency": "USD",
    "amount": 500.00,
    "fee": 5.00,
    "status": "PENDING",
    "bankName": "Chase Bank",
    "bankAccountNumber": "****6789",
    "firstName": "John",
    "lastName": "Doe",
    "initiatedAt": "2026-01-18T10:30:00.000Z"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

For crypto payouts, bankName and bankAccountNumber are replaced with protocol, address, and transactionHash. For business beneficiaries, the payload includes businessName instead of firstName/lastName.

Field	Type	Description
`payoutId`	string	Unique payout identifier
`type`	string	Payout type (`fiat` or `crypto`)
`currency`	string	Payout currency
`amount`	number	Payout amount
`fee`	number	Payout fee
`status`	string	Payout status
`bankName`	string	Destination bank name (fiat only)
`bankAccountNumber`	string	Destination account number (fiat only)
`firstName`	string	Beneficiary first name (fiat individual only)
`lastName`	string	Beneficiary last name (fiat individual only)
`businessName`	string	Beneficiary business name (fiat business only)
`protocol`	string	Blockchain protocol (crypto only)
`address`	string	Wallet address (crypto only)
`transactionHash`	string	Transaction hash (crypto only)
`initiatedAt`	string	Payout initiation timestamp

payout.completed

{
  "id": "evt_payout_def456",
  "type": "payout.completed",
  "data": {
    "payoutId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "fiat",
    "currency": "USD",
    "amount": 500.00,
    "fee": 5.00,
    "status": "SUCCESS",
    "bankName": "Chase Bank",
    "bankAccountNumber": "****6789",
    "firstName": "John",
    "lastName": "Doe",
    "completedAt": "2026-01-18T10:30:05.000Z"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

For business beneficiaries, the payload includes businessName instead of firstName/lastName.

Field	Type	Description
`payoutId`	string	Unique payout identifier
`type`	string	Payout type (`fiat` or `crypto`)
`currency`	string	Payout currency
`amount`	number	Payout amount
`fee`	number	Payout fee charged
`status`	string	Payout status (SUCCESS)
`bankName`	string	Destination bank name (fiat only)
`bankAccountNumber`	string	Destination account number (fiat only)
`firstName`	string	Beneficiary first name (fiat individual only)
`lastName`	string	Beneficiary last name (fiat individual only)
`businessName`	string	Beneficiary business name (fiat business only)
`protocol`	string	Blockchain protocol (crypto only)
`address`	string	Wallet address (crypto only)
`transactionHash`	string	Transaction hash (crypto only)
`completedAt`	string	Payout completion timestamp

payout.failed

{
  "id": "evt_payout_ghi789",
  "type": "payout.failed",
  "data": {
    "payoutId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "fiat",
    "currency": "USD",
    "amount": 500.00,
    "fee": 5.00,
    "status": "FAILED",
    "bankName": "Chase Bank",
    "bankAccountNumber": "****6789",
    "firstName": "John",
    "lastName": "Doe",
    "failureReason": "Payout failed",
    "completedAt": "2026-01-18T10:30:10.000Z"
  },
  "createdAt": "2026-01-18T10:30:10.000Z"
}

For business beneficiaries, the payload includes businessName instead of firstName/lastName.

Field	Type	Description
`payoutId`	string	Unique payout identifier
`type`	string	Payout type (`fiat` or `crypto`)
`currency`	string	Payout currency
`amount`	number	Payout amount
`fee`	number	Payout fee (may be refunded)
`status`	string	Payout status (FAILED)
`bankName`	string	Destination bank name (fiat only)
`bankAccountNumber`	string	Destination account number (fiat only)
`firstName`	string	Beneficiary first name (fiat individual only)
`lastName`	string	Beneficiary last name (fiat individual only)
`businessName`	string	Beneficiary business name (fiat business only)
`protocol`	string	Blockchain protocol (crypto only)
`address`	string	Wallet address (crypto only)
`transactionHash`	string	Transaction hash (crypto only)
`failureReason`	string	Reason for failure
`completedAt`	string	Failure timestamp

payout.reversed

Sent when a payout that had already completed is returned by the beneficiary bank and reversed. The payout amount is restored to the sender's wallet balance and any withdrawal fee charged on completion is refunded.

{
  "id": "evt_payout_jkl012",
  "type": "payout.reversed",
  "data": {
    "payoutId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "fiat",
    "currency": "USD",
    "amount": 100,
    "fee": 0.00,
    "status": "REVERSED",
    "bankName": "Example Bank",
    "bankAccountNumber": "****6124",
    "firstName": "John",
    "lastName": "Doe",
    "reversedAt": "2026-10-06T09:21:14.562Z"
  },
  "createdAt": "2026-10-06T09:21:14.562Z"
}

For business beneficiaries, the payload includes businessName instead of firstName/lastName.

Field	Type	Description
`payoutId`	string	Unique payout identifier
`type`	string	Payout type (`fiat` or `crypto`)
`currency`	string	Payout currency
`amount`	number	Payout amount restored to the wallet
`fee`	number	Payout fee charged on completion (refunded on reversal)
`status`	string	Payout status (REVERSED)
`bankName`	string	Destination bank name (fiat only)
`bankAccountNumber`	string	Destination account number (fiat only)
`firstName`	string	Beneficiary first name (fiat individual only)
`lastName`	string	Beneficiary last name (fiat individual only)
`businessName`	string	Beneficiary business name (fiat business only)
`protocol`	string	Blockchain protocol (crypto only)
`address`	string	Wallet address (crypto only)
`transactionHash`	string	Transaction hash (crypto only)
`reversedAt`	string	Reversal timestamp

wallet.credited

{
  "id": "evt_wallet_abc123",
  "type": "wallet.credited",
  "data": {
    "inflowId": "f7a8b9c0-d1e2-3456-abcd-ef7890123456",
    "currency": "USD",
    "amount": 500.00,
    "source": "WALLET_DEPOSIT",
    "providerReference": "DEP123456789",
    "senderName": "John Doe",
    "senderAccountNumber": "0123456789",
    "senderBankCode": "BARCGB22",
    "senderBankCodeType": "BIC",
    "paymentReference": "INV-4821",
    "paymentRail": "SEPA_INSTANT"
  },
  "createdAt": "2026-01-18T10:30:00.000Z"
}

senderName, senderAccountNumber, senderBankCode, senderBankCodeType, paymentReference and paymentRail are only present for fiat bank deposits (sourced from the bank credit advice). They are omitted for crypto deposits and for the destination leg of a currency conversion, where no external bank sender exists.

Field	Type	Description
`inflowId`	string	UUID of the inflow that credited the wallet
`currency`	string	Currency credited
`amount`	number	Amount credited
`source`	string	Origin of the credit (e.g. `WALLET_DEPOSIT`, `WALLET_EXCHANGE`)
`providerReference`	string	Upstream provider reference for the credit
`senderName`	string	Originating bank sender name (fiat deposits only)
`senderAccountNumber`	string	Originating bank sender account number (fiat deposits only)
`senderBankCode`	string	Originating bank identifier — SWIFT/BIC, sort code, routing number, bank code or bank name (fiat deposits only)
`senderBankCodeType`	string	How to interpret `senderBankCode`: `BIC`, `SORT_CODE`, `ROUTING_NUMBER`, `BANK_CODE` or `BANK_NAME` (fiat deposits only)
`paymentReference`	string	The reference/narration on the originating bank transfer (fiat deposits only)
`paymentRail`	string	The payment rail/network the transfer arrived on, normalised across providers to a standard set: `FASTER_PAYMENTS`, `BACS`, `CHAPS`, `SWIFT`, `SEPA`, `SEPA_INSTANT`, `FEDWIRE`, `ACH`, `TARGET2`, `UNKNOWN` (fiat deposits only)

wallet.debited

{
  "id": "evt_wallet_def456",
  "type": "wallet.debited",
  "data": {
    "outflowId": "550e8400-e29b-41d4-a716-446655440000",
    "currency": "USD",
    "amount": 250.00,
    "destination": "BANK_ACCOUNT"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

Field	Type	Description
`outflowId`	string	UUID of the outflow that debited the wallet
`currency`	string	Currency debited
`amount`	number	Amount debited
`destination`	string	Where the funds went: `BANK_ACCOUNT` (external fiat payout), `CRYPTO_WALLET` (on-chain payout), or `WALLET` (internal transfer)

Event Types

Signature Verification