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",
    "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.

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)
`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",
    "completedAt": "2026-01-18T10:30:05.000Z"
  },
  "createdAt": "2026-01-18T10:30:05.000Z"
}

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)
`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",
    "failureReason": "Payout failed",
    "completedAt": "2026-01-18T10:30:10.000Z"
  },
  "createdAt": "2026-01-18T10:30:10.000Z"
}

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)
`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

Event Types

Signature Verification