> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# API - Apr 24, 2025

Added

### 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 "MGP `PlatformTradingName`"
  * `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](/guides/payment-methods/banking/virtual-iban) 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](/api-reference/virtual-accounts/view-virtual-account-availabilities)
* [POST Create a Virtual Account](/api-reference/virtual-accounts/create-virtual-account)
* [PUT Deactivate a Virtual Account](/api-reference/virtual-accounts/deactivate-virtual-account)
* [GET View a Virtual Account](/api-reference/virtual-accounts/view-virtual-account)
* [GET List Virtual Accounts for a Wallet](/api-reference/virtual-accounts/list-virtual-accounts-wallet)

The following [webhook](/webhooks) 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](/errors/codes/002703) – Refused due to user UserCategory: PAYER

See the [guide](/guides/payment-methods/banking/virtual-iban#functional-errors) for more details.