Skip to main content
A static virtual account is one of your business’s collection accounts: a permanent number you can print on invoices, give to a branch, or show at checkout. Each payment into it settles on to your business’s account at the bank. Needs the VIRTUAL_ACCOUNTS feature and virtual-accounts:write. In live mode the bank must also have approved your business and recorded your settlement account.

Create one

  • name_status starts pending while the bank’s provider names the number, then becomes confirmed (or failed). You’ll get va.name.confirmed or va.name.failed.
  • settlement_account is the account at the bank the payments go on to, or null when it follows your business’s default, which the bank records.

Rename it, or name a number

PATCH /v1/virtual-accounts/{accountId} changes the name payers see, and/or the label. Send a person’s name (first_name, last_name, optional middle_name) or free text (account_name), not both.
  • A number from the provider’s pool is renamed there first: 202, name_status pending, and a second rename meanwhile is 409 (code 25).
  • A number from one of your number patterns is named at once: 200.
PUT /v1/virtual-accounts/numbers/{accountNumber} names a number under one of your patterns, even before its first payment. If nobody holds it yet, it creates the account (201).

Payments and settlements

  • GET /v1/virtual-accounts/{accountId}/payments lists the payments into it.
  • GET /v1/virtual-accounts/{accountId}/settlements lists each payment passed on to your settlement account: queued, settled or failed.
  • GET /v1/collection-settlements lists them across every collection account.
Each payment also arrives as a webhook: va.payment.success when credited, and va.settlement.completed when passed on to your account at the bank.