Virtual IBANs

Regions	See IBAN countries and currencies
Currencies
Refunds	Supported via payouts
Disputes	Not supported

Introduction

Mangopay enables you to create an IBAN or local account identifier attached to a wallet. Once created, any funds wired by the user to the dedicated account are credited automatically to the associated wallet, which simplifies reconciliation and improves the user experience.

In the API, the Virtual Account object allows you to create and manage dedicated virtual IBANs for your users’ wallets. You can also see local and international pay-in capabilities available to your platform.

Note - Replaces deprecated Banking Alias feature

The Virtual Account endpoints replace the deprecated Banking Alias endpoints, which will be removed in Q3 2026.

Platforms using Banking Aliases must plan to change their integration.

All Banking Alias objects are available via the GET View a Virtual Account endpoint, using the Banking Alias Id and WalletId as path parameters.

The Virtual Account endpoints bring many advantages over the Banking Alias feature:

• Extended country and currency coverage, including country-specific IBANs for EUR countries and expansion into new international markets
• Multiple accounts per wallet
• Ability to open accounts in the name of the user thanks to user-owned accounts (see types below)
• Adherence to financial market standards (ISO 20022)
• Dedicated endpoint giving the countries and currencies available to your platform (GET View Virtual Account availabilities)

Any further product development or currency and country coverage will only be delivered on Virtual Accounts and not Banking Aliases.

SCT Instant on FR accounts

On FR virtual accounts and banking aliases (Country is FR), Mangopay accepts payments via the SEPA Instant Credit Transfer (SCT Inst) scheme.

This means that when your users initiate the payment with their bank, they can use SCT Inst if it is offered by their bank, and funds should arrive in about 25 seconds.

FPS on GB accounts

On GB virtual accounts and banking aliases (Country is GB), users can make payments via the UK’s Faster Payment System, meaning funds typically arrive in a matter of seconds (possible delay up to 2 hours).

How it works

As a payment method, virtual accounts allow a user to wire funds directly to their wallet. You should create the account first before inviting the user to wire the funds.

Set up the account

The steps to set up the virtual account are:

1. Create a wallet for the account

   Call the POST Create a Wallet endpoint and specify its currency.

   Caution – Currency must be consistent

   The currency of the wallet must match the currency of the account you intend to create. See countries and currencies for details.

2. Create the virtual account

   Call the POST Create a Virtual Account endpoint, specifying the Country and VirtualAccountPurpose, whether COLLECTION or USER_OWNED (see types for details).

   The response shows the details of the account and its Status, which must be ACTIVE to receive funds.

   Note – UK Confirmation of Payee (CoP)

   For GB virtual accounts, it takes approximately 48 hours for the account to be fully recognized by all banks through the UK’s Confirmation of Payee (CoP) scheme.

   Once the virtual account is ACTIVE it can technically receive funds. Depending on the user’s bank, during the first 48 hours they may be shown a CoP alert but be able to ignore it, or be prevented from proceeding with the wire transfer.

   Best practice – Set up webhook for active accounts

   The account Status must be ACTIVE to receive funds, otherwise any funds sent to the account details are returned.

   Therefore, you are strongly advised to set up a webhook for the VIRTUAL_ACCOUNT_ACTIVE event type to be notified that the account is ready for use.

   You should also set up the other webhooks for the other status changes.

Collect payments

Once the Virtual Account is set up and its Status is Active, the user can wire funds to it.

The payment flow is as follows:

1. Obtain the account details and create a reference

   Call the GET View a Virtual Account endpoint to obtain the account details in international or local formats.

   You can also create a unique custom reference for the user to use for the payment.

   Caution – Ensure account is ACTIVE

   You must always ensure the account is ACTIVE before inviting a payment, otherwise the funds will be returned.

   See also the note about delayed UK CoP recognition for GB accounts.

2. Present the payment details to the user

   Display the account details along with your custom reference.

   Best practice – Display instructions, account holder name, and account number clearly to the user

   As well as the account number or IBAN, ensure you display the AccountOwner clearly as well. For EUR SEPA payments, both data points are used for Verification of Payee (VOP).

   Your user must understand that they need to initiate the bank wire transfer on their side with their bank.

   Ensure your messaging is clear and that the payment details are easy to copy and use.

3. Wait for the user to make the payment via online banking

   The user requests the wire transfer via their online banking app, specifying the virtual account as the payee.

4. Handle webhook notification when Mangopay creates the pay-in and credits the wallet

   On receipt of the funds, Mangopay automatically creates an External Instruction Bank Wire PayIn.

   Set up a webhook for the PAYIN_NORMAL_SUCCEEDED event type to be notified of this.

   You can then use the GET View a PayIn endpoint to get the custom WireReference you provided to the user, as well as confirm the amount and status.

   The pay-in’s BankingAliasId contains the unique identifier of the Virtual Account.

Status

The Status of the Virtual Account can have the following values:

• PENDING – The account creation request is being processed and full account details may not yet be returned. Any funds sent to the account are returned (if account details exist). PENDING can transition to ACTIVE or FAILED.
• ACTIVE – The account is active and can receive funds (see note about delayed UK CoP recognition for GB accounts). ACTIVE can transition to BLOCKED or CLOSED.
• BLOCKED – The account is blocked and is not active. Any funds sent to the account are returned. This temporary status may be used during processes relating to user verification or fraud screening. BLOCKED can transition to ACTIVE or CLOSED.
• CLOSED – The account has been deactivated and is closed. Any funds sent to the account are returned. This is a final state.
• FAILED – The account creation request failed or was rejected. This final state is rare. Any funds sent to the account are returned (if account details exist). Depending on when the failure occurred, the following fields may be null:
  • AccountOwner
  • LocalAccountDetails.Address
  • LocalAccountDetails.Account
  • InternationalAccountDetails.Address
  • InternationalAccountDetails.Account

The possible Status changes are summarized in this diagram:

Webhooks

You should set up webhook notifications for the following event types to be notified when a Virtual Account changes status:

• VIRTUAL_ACCOUNT_ACTIVE
• VIRTUAL_ACCOUNT_BLOCKED
• VIRTUAL_ACCOUNT_CLOSED
• VIRTUAL_ACCOUNT_FAILED

There is no event type corresponding to the PENDING status.

Functional errors

In most cases, the virtual account passes from PENDING to ACTIVE immediately or within a few seconds. You are strongly advised to rely on the VIRTUAL_ACCOUNT_ACTIVE webhook.

In some rare cases, a USER_OWNED Virtual Account object can be created (the POST endpoint returns 200) but then subsequently fail with the following ResultCode errors because the user doesn’t meet the requirements:

• 002703 – User is not an Owner (for USER_OWNED)
• 002981 – User is not KYC verified (for USER_OWNED)

IBAN countries and currencies

Mangopay offers IBANs for the following countries, specified in the Country parameter of both the Virtual Account object and the legacy Banking Alias object.

When you create an account, the Country must correspond to the Currency of the account’s Wallet. If a payment is attempted to the account in a different currency than the wallet currency, the payment is returned to the payer and the wallet is not credited.

The following tables summarize the account coverage available to platforms who have contracted with Mangopay S.A. (in the EEA) and Mangopay UK Ltd. (in the UK). It also shows a comparison between the Virtual Account endpoints and the legacy Banking Alias (on which no further coverage changes are planned).

EEA

IBAN country	Wallet currency	Virtual Account	Banking Alias
AU - Australia	AUD	Planned
CA - Canada	CAD
CZ - Czechia	CZK	Planned
DK - Denmark	DKK
DE - Germany	EUR
ES - Spain	EUR
FR - France	EUR
GB - UK	GBP
HU - Hungary	HUF	Planned
LI - Lichtenstein	CHF	Planned
LU - Luxembourg	EUR
NO - Norway	NOK	Planned
PL - Poland	PLN	Planned
SE - Sweden	SEK	Planned
US - USA	USD

Platforms can see what countries and currencies are available to them at any time using the GET List Virtual Account availabilities endpoint.

On-demand non-local currencies

In addition to the coverage above, Mangopay is able to offer virtual accounts in additional currencies by request of platforms.

• Available currencies: AED, AUD, CAD, CHF, CNH, CZK, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, TRY, USD, ZAR
• Payment rails: SWIFT
• Account format: DK IBAN only
• Available Virtual Account types: COLLECTION and USER_OWNED
• Limitations: Available for payments from business accounts only (not personal ones)

Contact Mangopay via the Dashboard or Sales contact form for more information.

Account formats

The virtual account details are available in two response parameters:

• LocalAccountDetails – An object containing the Address and Account details in local format, based on the Virtual Account Country. Note that the properties of the Account object vary depending on the Country.
• InternationalAccountDetails – An array of objects containing the Address and Account in international format (typically IBAN/BIC but this may change). Where country-specific IBANs exist for the account, multiple objects are returned.

Best practice – Retrieve fields and values dynamically

You should retrieve the child objects, properties and values of the LocalAccountDetails and InternationalAccountDetails to present to the user.

The properties of these objects may vary, so dynamic retrieval allows you to ensure that details are always presented correctly.

Types

There are two types of virtual accounts, defined by the VirtualAccountPurpose on creation:

• COLLECTION – Owned by Mangopay and usable by platforms and/or users for the purpose of collecting and reconciling incoming funds paid by users. Payouts are generally prohibited from the associated wallet except for refunds. The user can be categorized as a Payer or an Owner. The AccountOwner is “MGP PlatformTradingName”
• USER_OWNED – Owned by the user owning the wallet, enabling them to accept and store funds and make payments. KYC verification is required and the user must be categorized as an Owner. The AccountOwner is Natural User’s “FirstName LastName” or Legal User’s “Name”.

Note – One VirtualAccountPurpose per wallet

You can create multiple virtual accounts attached to the same wallet, but they must all have the same purpose (either COLLECTION or USER_OWNED).

The following table summarizes the differences between the two types:

	Collection account	User-owned account
Purpose	Collection and reconciliation of funds by the platform	User’s acceptance and storing of funds
Account owner	Mangopay S.A. or Mangopay UK Ltd.	Wallet owner
Account holder name example	”MGP PlatformTradingName"	"FirstName LastName” (Natural user) or “Name” (Legal user)
Allowed user category	Owner or Payer	Owner
KYC verification	Not required	Required
Payouts	Prohibited from the associated wallet, except for refunds returning funds to their origin	Authorized from the associated wallet

Note – User address data required for USER_OWNED account

User-owned virtual accounts require the following data to be provided in the corresponding User object:

• Address for a Natural User
• LegalRepresentativeAddress for a Legal User

This address data is not required for the user to be an Owner or to be KYC validated, but it must be present to successfully create a USER_OWNED Virtual Account. This data is not required for COLLECTION accounts.

Collection accounts

Collection accounts allow users to wire funds to their wallet using a designated virtual IBAN. Once created, any funds received on the IBAN are automatically credited to the wallet. The IBAN is owned by Mangopay, and the name of the account reflects both Mangopay and the platform’s name in the format “MGP PlatformTradingName”.

Collection accounts need to be attached to the wallet of the user making the pay-in, meaning that you need to create one Virtual Account object per user. This first user can be categorized as a Payer and they don’t need to be KYC verified. In your workflow, you can trigger a transfer from the wallet to a second user, who must be categorized as an Owner to receive the transfer.

This type of account is mainly used for collecting and reconciling incoming funds, making it ideal for platforms that want to streamline these processes. Payouts are prohibited unless they’re for a refund.

User-owned accounts

User-owned accounts allow platforms to create a unique IBAN for a specific user. Once created, the IBAN can be used to receive pay-ins, and the wallet can be used to make transfers and payouts. Because this IBAN is owned by the user, they must be categorized as an Owner and be KYC verified. The account holder can collect and make payments and transfer funds with full functionality.

Related resources

Endpoints

The Virtual Account object