Create USD Virtual Accounts

Virtual Accounts enable customers to process USD pay-ins by generating unique banking credentials, including routing and account numbers, which accurately identify and credit third-party fiat deposits to a specific beneficiary.

Create a virtual account

Virtual accounts can only be created for a beneficiary who has completed the Caliza KYX process.

To create a new virtual account, send a POST request to /v1/beneficiaries/{beneficiaryId}/virtualAccounts. This endpoint creates a new virtual account for the beneficiary in the specified currency and region. Virtual accounts enable beneficiaries to receive funds through unique account identifiers (account number + routing number) without having an actual bank account. Each virtual account is tied to a specific currency and can receive deposits via supported payment rails. You can create multiple virtual accounts per beneficiary for different currencies.

Request fields

The BeneficiaryVirtualAccountRequest object accepts the following fields:

When to use suffix, label, and defaultPayor

Use these fields when a beneficiary needs more than one virtual account (for example, one VA per payment source or channel). The suffix is appended to the account title at the banking provider. The label is a Caliza-side tag you can use to identify VAs when calling the list or get endpoints, without affecting the bank account title. Multiple VAs can be created with the same title and distinguished by their labels. The defaultPayor flag specifies which of those VAs should appear as the payor; if you do not send defaultPayor, the first VA is used as the default.

Example request

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/virtualAccounts' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "suffix": "{{SUFFIX}}",
    "defaultPayor": {{DEFAULT_PAYOR}},
    "label": "{{LABEL}}"
}'

Response

When successful, the API returns a 204 No Content status. The account details are generated asynchronously. You can retrieve the virtual account details using the GET /v1/beneficiaries/{beneficiaryId}/virtualAccounts endpoint or by listening for the PAY_IN_ACCOUNT_CREATED webhook event.

Verify account

To verify the system created the virtual account, you can list all virtual accounts associated with the beneficiary by running:

curl -s --location --request GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{beneficiary_id}/virtualAccounts' \
--header 'Authorization: Bearer Your_Token' \
--header 'Content-Type: application/json'

[
    {
        "id": "abc123def456",
        "accountNumber": "083a1637-219b-487b-a6dd-5e27252ddafd",
        "routingNumber": "021214891",
        "receiverName": "Jane Smith Valid_MainAccount",
        "receiverAddress": "1600 Pennsylvania Avenue NW, 20500 Washington, DC, US",
        "receiverBankName": "CROSS RIVER BANK",
        "swiftCode": "TBD",
        "receiverBankAddress": "2115 Linwood Ave, Fort Lee, NJ 07024, United States",
        "label": "Payroll"
    }
]

📘

Remember to replace beneficiary_id and Your_Token with the appropriate values.

Where:

• id: The unique identifier for the virtual account.
• accountNumber: The account number for the virtual account.
• routingNumber: The routing number associated with the virtual account.
• receiverName: The name of the account holder.
• receiverAddress: The address of the account holder.
• receiverBankName: The name of the bank that holds the virtual account.
• swiftCode: The SWIFT (Society for Worldwide Interbank Financial Telecommunication) code for international transactions.
• receiverBankAddress: The address of the bank that holds the virtual account.
• label: The label assigned at creation to distinguish this virtual account from others (if provided).

The virtual account has been created and is ready to use for simulating transactions.

Webhook events for virtual accounts

The Caliza API uses webhook events to notify you of various virtual account-related events. The webhook for virtual accounts includes:

{
  "operation": "PAY_IN_ACCOUNT_CREATED",
  "resourceId": "{{beneficiaryId}}",
  "createdAt": "2025-06-27T17:48:03.495334871",
  "integratorId": "{{integratorId}}",
  "beneficiaryId": "{{beneficiaryId}}",
  "data": {
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "receiverName": "John Doe",
    "receiverBankName": "Global Bank",
    "receiverBankAddress": "123 Main Street, New York, NY, USA",
    "swiftCode": "DEUTDEFF"
  }
}

Where:

• operation: The type of operation that triggered the webhook (for example, PAY_IN_ACCOUNT_CREATED).
• resourceId: The ID of the beneficiary associated with the webhook event.
• createdAt: The timestamp when the webhook event was created.
• integratorId: The ID of the integrator associated with the beneficiary.
• beneficiaryId: The ID of the beneficiary associated with the webhook event.
• data: An object containing details about the virtual account, including account number, routing number, receiver name, bank name, bank address, and SWIFT code.

Next Steps