Skip to main content
USD Virtual Account operations trigger webhooks at different stages of the account lifecycle. Subscribe to these events to automate your internal workflows.

​
1. virtualaccount.creation.completed

This webhook is sent when a USD virtual account has been successfully provisioned after an initial PROCESSING state. It contains the full bank account details (account number, bank name, SWIFT code, etc.) that you can then share with your customer.

​
Payload Example

{
  "event": "virtualaccount.creation.completed",
  "data": {
    "id": "8baf5a4a-b1b9-48fb-a492-b5041db9cfe1",
    "reference": "REF_8899562444KLLOPLTTPKNMTYLP900POLOPI",
    "accountName": "CHECK Ng Ltd",
    "account": {
      "name": "CHECK Ng Ltd",
      "bankName": "DBS Bank Limited",
      "number": "372385345434",
      "sortCode": "MOOLAHGO",
      "swiftCode": "DBSSSGSGXXX",
      "bankAddress": "12 Marina Boulevard, DBS Asia Central Marina Bay Financial Tower"
    },
    "currency": "USD",
    "country": "US",
    "status": "ACTIVE",
    "isPermanent": true,
    "created": "2025-12-18T09:57:44.127397385Z"
  }
}

​
Response Breakdown

FieldTypeDescription
eventstringThe name of the event (virtualaccount.creation.completed).
data.idstringUnique identifier for the virtual account.
data.referencestringThe unique reference supplied during account creation.
data.accountNamestringThe display name for the account.
data.account.namestringThe registered name on the bank account.
data.account.bankNamestringThe name of the issuing bank.
data.account.numberstringThe virtual account number.
data.account.sortCodestringThe bank sort code or routing identifier.
data.account.swiftCodestringThe SWIFT/BIC code for international transfers.
data.account.bankAddressstringThe physical address of the issuing bank.
data.currencystringThe account currency (USD).
data.countrystringThe account country (US).
data.statusstringThe current status of the account (ACTIVE).
data.createdstringISO 8601 timestamp of account creation.

​
2. virtualaccount.completed (Funding)

This webhook is sent when a USD virtual account has been successfully credited with funds. It provides details about the deposit, including fees and settlement information.

​
Payload Example

{
  "event": "virtualaccount.completed",
  "data": {
    "id": "8947fe83-3374-4bbd-a7f6-465481cb4baa",
    "referenceNumber": "AJE318KMPAAJB",
    "amount": "1000",
    "type": "FUNDING",
    "state": "COMPLETED",
    "destination": "USD wallet",
    "narration": "narration",
    "country": "US",
    "currency": "USD",
    "fee": {
      "vat": "10.00",
      "stampDuty": "100.00",
      "base": "10.00"
    },
    "settlementAmount": "880.00",
    "source": {
      "bankName": "Best bank",
      "accountName": "John Sam",
      "accountNumber": "3124458172"
    },
    "customer": {
      "email": "[email protected]",
      "reference": "REF_SXDMSDA13J32",
      "account": {
        "name": "Preston Berge",
        "bankName": "DBS Bank Limited",
        "number": "656633887809",
        "sortCode": "MABKCSKI"
      }
    },
    "created": "2025-12-02T12:34:46.755211501Z",
    "processed": "2025-12-02T12:34:46.755211501Z"
  }
}

​
Response Breakdown (Funding)

​
Core Transaction Fields

FieldTypeDescription
eventstringThe name of the event (virtualaccount.completed).
data.idstringUnique identifier for the funding transaction.
data.referenceNumberstringUnique reference number assigned to the transaction.
data.amountstringThe total gross amount of the transaction in USD.
data.typestringThe type of transaction (FUNDING).
data.statestringThe final state of the transaction (COMPLETED or FAILED).
data.destinationstringThe destination wallet (e.g., USD wallet).
data.currencystringThe currency of the transaction (USD).

​
Fee Breakdown

FieldTypeDescription
data.fee.vatstringThe Value Added Tax portion of the fee.
data.fee.stampDutystringThe stamp duty portion of the fee.
data.fee.basestringThe base processing fee.
data.settlementAmountstringThe final amount settled after all fees.

​
Customer Details

FieldTypeDescription
data.customer.emailstringThe customer’s email address.
data.customer.referencestringThe unique reference for the virtual account.
data.customer.account.numberstringThe virtual account number that was funded.

​
Handling These Webhooks

When you receive these webhooks, you should:
  1. Verify the signature – Ensure the webhook is authentic.
  2. Check the state/status – Confirm it is ACTIVE or COMPLETED.
  3. Match the reference – Use the reference field to link the event to your internal records.
  4. Respond with 200 OK – Acknowledge receipt of the webhook to prevent retries.