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