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 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:

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.