Collect with a virtual account

A virtual account is an account number that belongs to one of your customers, or to one order or invoice. Anyone can pay it from any bank app, and the credit posts to the right balance without you matching anything by hand.

1. Create the numbers

POST /account/virtual creates a virtual account for a financial account, at each bank you name. The response lists each accountNumber with its bank. Show them in your app.

2. Someone pays

A payer sends money to one of the numbers from any bank. When the credit arrives it posts to the customer’s balance, and you receive a signed virtual_account.credited webhook.

switch (event.type) {
  case "virtual_account.credited":
    return onIncomingPayment(event.data); // credit the order, notify the customer
  case "virtual_account.credit_reversed":
    return onReversal(event.data);        // subscribe to this one too
}

3. Read the history

GET /account/virtual/{reference}/credits lists every funding notification received for a virtual account, so you can reconcile against your own records.

When something goes wrong

• A credit didn’t post. Retry it with POST /account/virtual/credit/{reference}/replay. Replay is idempotent: a doubled replay posts once.
• You need to stop payments. POST /account/virtual/{reference}/block, and unblock to reopen it.
• You missed a webhook. Replay it from the delivery log. See Replay and recovery.

Account numbers come through a partner bank, so availability depends on that bank.