API - Apr 24, 2025
Virtual Account endpoints, replacing legacy Banking Alias feature
Platforms can take advantage of Virtual Accounts, which replace the existing Banking Alias feature.
A Virtual Account is a dedicated IBAN or local account identifier that platforms can attach to a specific wallet, in the same way as Banking Aliases.
Virtual Accounts bring several key improvements:
- Two types of account indicated by
VirtualAccountPurpose
:COLLECTION
- Owned by Mangopay and usable by platforms and/or users for the purpose of collecting and reconciling incoming funds paid by users.AccountOwner
is “MGPPlatformTradingName
”USER_OWNED
- Owned by the user owning the wallet, enabling them to accept and store funds and make payments.AccountOwner
is Natural User’s “FirstName
LastName
” or Legal User’s “Name
”.
- Extended currency and country coverage, plus further expansion planned in future.
- Full local and international bank details for each account.
- Adherence to financial market standards (ISO 20022).
- Ability to retrieve available countries and currencies for your platform at any time via a dedicated endpoint.
For full details of features and user requirements for each purpose, see the updated Virtual IBANs guide.
Virtual Accounts allows a more localized payment experience to facilitate automated reconciliation. While existing Banking Aliases remain active and the endpoints continue to be supported, we encourage platforms to integrate virtual accounts to benefit from the new features.
The following endpoints have been added:
- GET View Virtual Account availabilities
- POST Create a Virtual Account
- PUT Deactivate a Virtual Account
- GET View a Virtual Account
- GET List Virtual Accounts for a Wallet
The following webhook event types have been added, reflecting the Virtual Account’s asynchronous state machine:
VIRTUAL_ACCOUNT_ACTIVE
VIRTUAL_ACCOUNT_BLOCKED
VIRTUAL_ACCOUNT_CLOSED
VIRTUAL_ACCOUNT_FAILED
While the majority of virtual accounts are created immediately, a new ResultCode
error has been added to accommodate a rare case where a USER_OWNED
account fails after the creation request because the user does not have the UserCategory
OWNER
:
- 002703 – Refused due to user UserCategory: PAYER
See the guide for more details.