Webhooks

Bank Account Status Update

Fired when a virtual account finishes provisioning — either becoming active or being declined by the partner bank.

Use this webhook to

Know the moment a foreign-currency (USD/EUR/GBP) account finishes provisioning
Know when the partner bank declines an account, and why
Avoid polling Get Customer Accounts while waiting on a pending account

Events

Event	Fired when
`virtual_account.created`	An account becomes `active`
`virtual_account.failed`	The partner bank declines an account

Payloads

virtual_account.created

{
  "event": "virtual_account.created",
  "data": {
    "customer_uuid": "…",
    "tracking_id": "EXTACCT…",
    "account_number": "1234567890",
    "account_name": "John Doe",
    "bank_name": "Safe Haven MFB",
    "bank_code": "090286",
    "provider": "safehaven",
    "currency": "NGN",
    "status": "active",
    "date_created": "1782947655"
  }
}

virtual_account.failed

{
  "event": "virtual_account.failed",
  "data": {
    "customer_uuid": "…",
    "tracking_id": "EXTACCT…",
    "provider": "",
    "currency": "USD",
    "status": "failed",
    "reason": "Proof of address document rejected by partner bank"
  }
}

Payload fields

Field	Type	Description
`customer_uuid`	string	Customer this account belongs to
`tracking_id`	string	Our identifier for this account
`account_number`	string	Account number — created event only
`account_name`	string	Name on the account — created event only
`bank_name` / `bank_code`	string	Issuing bank details — created event only
`provider`	string	`safehaven`, `dotbank`, `9psb`
`currency`	string	Account currency
`status`	string	`active` or `failed`
`date_created`	string	Unix timestamp — created event only
`reason`	string	Present on `virtual_account.failed` — why the partner bank declined

Questions? Email [email protected]. Also on GitBook.