Virtual Accounts Whitelisting

Before a virtual account can start receiving funds, you'll need to whitelist a source account.

A source account is the bank account that your customer will be sending funds from — for example, their personal or business bank account. Whitelisting it tells the system to expect funds from that account and ensures any deposits are accepted and processed correctly.

Any deposits arriving from from non-whitelisted sources will be returned.

Why whitelisting is requiredCopy Anchor Link

Whitelisting is a compliance requirement. It ensures that every virtual account can only receive funds from a known, verified source. This helps meet anti-money laundering (AML) obligations by creating a clear, auditable link between a virtual account and the customer it belongs to — and prevents funds from unexpected or unverified third parties from being accepted.

How it worksCopy Anchor Link

Here's the typical setup flow:

1. Create the virtual account.
2. Whitelist the source account your customer will be sending funds from.
3. That's it — deposits from the whitelisted source will now be accepted, and anything else will be returned.

The fields used to identify a source account vary by currency and payment rail. For AUD virtual accounts, source accounts are identified by their BSB and account number.

EndpointsCopy Anchor Link

List whitelisted accountsCopy Anchor Link

GET /api/v1/customers/{customerId}/virtual-accounts/{virtualAccountId}/whitelist-accounts

{
  "count": 1,
  "data": [
    {
      "id": 1791,
      "account_number": "401341834",
      "bsb_number": "112-879",
      "account_status": "enabled"
    }
  ]
}

Add a whitelisted accountCopy Anchor Link

Requires an idempotency-key header.

POST /api/v1/customers/{customerId}/virtual-accounts/{virtualAccountId}/whitelist-accounts

// Request
{
  "source_account": {
    "account_number": "401341834",
    "bsb_number": "112-879"
  }
}

// Response
{
  "id": 1791,
  "account_number": "401341834",
  "bsb_number": "112-879",
  "account_status": "enabled"
}

Update a whitelisted accountCopy Anchor Link

Update the details or status of an existing whitelist entry. Temporarily disabling a source account will cause any deposits from it to be returned until you re-enable it.

Requires an idempotency-key header.

PATCH /api/v1/customers/{customerId}/virtual-accounts/{virtualAccountId}/whitelist-accounts/{sourceAccountId}

// Request
{
  "account_number": "401341834",
  "bsb_number": "112-879",
  "account_status": "disabled"
}

// Response
{
  "id": 1791,
  "account_number": "401341834",
  "bsb_number": "112-879",
  "account_status": "disabled"
}

Things to keep in mindCopy Anchor Link

• A virtual account with an empty whitelist — or where all entries are disabled — will return all incoming deposits to the sender.
• Whitelists are scoped to individual virtual accounts and aren't shared across accounts.
• Disabling an entry doesn't delete it. You can re-enable it at any time via an update request.
• There's no delete endpoint. If you want to permanently block a source, set its account_status to "disabled".