International accounts (GBP/USD/EUR)
GBP, USD, and EUR are received through VIBANs — virtual IBANs / account numbers backed by our FX banking partner. A sender pays the VIBAN over their local or international rail (IBAN + BIC for EUR, sort code + account number for GBP, routing/account or SWIFT for USD), the funds settle to your merchant wallet, and Swappr fires a wallet_funded webhook.
Two ownership modes
A VIBAN belongs to one of two owners, and that ownership determines how the inflow is attributed.
| Customer international account | Business / merchant international account | |
|---|---|---|
| Who owns it | One of your verified end-users | Your own treasury |
| Issued via | POST /v1/customers/{id}/virtual_accounts — see Issue a collection account | Provisioned for your merchant account (no per-customer call) |
wallet_funded payload | Carries a customer block (customer.id, customer.customer_reference) | No customer block — a merchant-pool credit |
| Use it for | Crediting a specific end-user (remittance / per-user balances) | Your own receivables / treasury inflows |
In both cases the merchant wallet is the account that’s credited — the difference is whether the inflow is attributed to a customer. Branch on event.customer?.id: present → credit that end-user; omitted → a business/treasury credit. See Attribution & balances.
Customer international accounts
Issue one per end-user with POST /v1/customers/{id}/virtual_accounts — the call is idempotent per (customer, currency) (one account per customer per currency), and the customer must be verified. The full issuing flow, pre-conditions, and the customer-as-sender note live on Issue a collection account; the endpoint spec is in the Customers API reference.
Business / merchant international accounts
A merchant international account is your own treasury VIBAN — funds paid to it are a straight merchant-pool credit with no customer block. Use it when you’re receiving your own money rather than collecting on behalf of an end-user. There’s no per-customer issuing call; the account is provisioned for your merchant wallet.
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 testing of the create + provision flow; switch to live for actual inflow testing.
Next
- Attribution & balances → — credit the right user from the
customerblock + pull history - CAD & Interac → — CAD doesn’t use a VIBAN
- Issue a collection account → — per-customer VIBAN issuing flow
- Customers API reference → — VIBAN endpoint spec + errors