Issue a collection account
Once a customer is verified, you can give them a dedicated international account to receive money — a virtual IBAN (VIBAN) for GBP / USD / EUR, or a CAD Interac e-Transfer routing address. Each VIBAN is bound to one customer + currency.
This page explains the model and the inflow-attribution flow. For the endpoint spec, see the Customers API reference.
GBP / USD / EUR use VIBANs; CAD uses Interac
- GBP / USD / EUR — issue a VIBAN with
POST /v1/customers/{id}/virtual_accounts. The call is idempotent per(customer, currency)— one account per customer per currency. - CAD — no VIBAN. Set the customer’s
interac_emailat create time and our FX rail routes inbound Interac transfers to your wallet automatically.
Pre-conditions: the customer must be verified, the currency must be GBP/USD/EUR, and your merchant account must hold an active wallet in that currency. NGN virtual accounts aren’t issued for customers this way.
A customer’s VBA is also their send account. In the individual flow, a GBP/USD/EUR payout leaves the sender’s own virtual account — so before you can pay out in a currency on a customer’s behalf, that customer needs an active VBA in it. A payout for a sender with no active VBA in the currency is rejected with sender_account_not_provisioned. (CAD sends via Interac and needs no VBA.) This is the individual-flow gate; the business/treasury flow instead uses the merchant’s own international account. See Individual vs business.
Provisioning is asynchronous
A freshly-issued VIBAN starts in provisioning while the upstream rail allocates the real account number — the account_number field stays empty until it lands. Subscribe to the virtual_account_activated webhook to know when it’s ready to receive.
Sandbox limitation: in the development environment, only NGN virtual accounts settle. GBP / USD / EUR VIBANs can be provisioned in sandbox and show as provisioning, but the account_number stays empty because no real bank-rail account is issued. Use sandbox for end-to-end integration testing of the create + provision flow; switch to live for actual inflow testing.
Attributing inflows back to the customer
When money lands at a customer’s VIBAN (or via Interac), Swappr fires a wallet_funded webhook carrying a customer block:
"customer": {
"id": "cus_xxxxxxxxxxxx",
"customer_reference": "your-user-reference"
}Use customer.customer_reference to credit the right user in your system. Your merchant (business) wallet is credited; per-user accounting on your side is your responsibility.
To tell Interac flows from bank-rail flows, branch on the event’s currency (CAD = Interac) — not the provider slug, which is internal and may change. The Interac sender’s email surfaces in sender.accountNumber (Swappr normalises every rail into one sender shape; see the sender-field table).
Seeing a customer’s full history
Every inflow and outflow attributed to a customer is queryable as one time-ordered feed — GET /v1/customers/{id}/transactions. See List customer transactions.
Next
- Customers API reference → — VIBAN endpoint spec + errors
- Webhooks → —
virtual_account_activated+wallet_fundedevent shapes