Virtual IBANs
| Regions | |
|---|---|
| Currencies | |
| Refunds | Not supported |
| 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 Banking Alias feature
The Virtual Account endpoints replace the legacy Banking Alias endpoints, which should be considered deprecated and no longer used.
New platforms should integrate using Virtual Accounts. While existing Banking Alias objects and endpoints continue to be supported, platforms are invited to change their integration to benefit from extended country and currency coverage. Any further country and currency expansion will only be delivered on virtual accounts.
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)
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.
Creating the account
The steps to set up the virtual account are:
You create a wallet for the account
You 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.
You create the virtual account
You 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.
Payment flow
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:
You obtain the account details and create a reference
You 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.
You present the payment details to the user
You display the account details along with your custom reference.
Best practice – Display instructions and details clearly to the user
Your user must understand that they need to initiate the bank wire on their side.
Ensure your messaging is clear and that the payment details are easy to copy and use.
The user makes the payment via online banking
The user requests the wire transfer via their online banking app, specifying the virtual account as the payee.
Mangopay creates the pay-in and credits the wallet
On receipt of the funds, Mangopay automatically creates an External Instruction Bank Wire PayIn.
You can be notified of this by setting up a webhook for the PAYIN_NORMAL_SUCCEEDED event type.
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).PENDINGcan transition toACTIVEorFAILED.ACTIVE– The account is active and can receive funds (see note about delayed UK CoP recognition forGBaccounts).ACTIVEcan transition toBLOCKEDorCLOSED.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.BLOCKEDcan transition toACTIVEorCLOSED.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 benull:CreditedUserIdAccountOwnerLocalAccountDetails.AddressLocalAccountDetails.AccountInternationalAccountDetails.AddressInternationalAccountDetails.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_ACTIVEVIRTUAL_ACCOUNT_BLOCKEDVIRTUAL_ACCOUNT_CLOSEDVIRTUAL_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:
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).
| IBAN country | Wallet currency | Virtual Account | Banking Alias |
|---|---|---|---|
| AU - Australia | AUD | Planned | |
| CA - Canada | CAD | Planned | |
| DK - Denmark | DKK | ||
| DE - Germany | EUR | ||
| ES - Spain | EUR | ||
| FR - France | EUR | ||
| LI - Lichtenstein | CHF | Planned | |
| LU - Luxembourg | EUR | ||
| GB - UK | GBP | ||
| NO - Norway | NOK | Planned | |
| PL - Poland | PLN | Planned | |
| SE - Sweden | SEK | Planned | |
| US - USA | USD | Planned |
| IBAN country | Wallet currency | Virtual Account | Banking Alias |
|---|---|---|---|
| AU - Australia | AUD | Planned | |
| CA - Canada | CAD | Planned | |
| DK - Denmark | DKK | ||
| DE - Germany | EUR | ||
| ES - Spain | EUR | ||
| FR - France | EUR | ||
| LI - Lichtenstein | CHF | Planned | |
| LU - Luxembourg | EUR | ||
| GB - UK | GBP | ||
| NO - Norway | NOK | Planned | |
| PL - Poland | PLN | Planned | |
| SE - Sweden | SEK | Planned | |
| US - USA | USD | Planned |
| IBAN country | Wallet currency | Virtual Account | Banking Alias |
|---|---|---|---|
| AU - Australia | AUD | Planned | |
| CA - Canada | CAD | Planned | |
| DK - Denmark | DKK | ||
| DE - Germany | EUR | ||
| ES - Spain | EUR | ||
| FR - France | EUR | ||
| LI - Lichtenstein | CHF | Planned | |
| LU - Luxembourg | EUR | ||
| GB - UK | GBP | ||
| NO - Norway | NOK | Planned | |
| PL - Poland | PLN | Planned | |
| SE - Sweden | SEK | Planned | |
| US - USA | USD | Planned |
Platforms can see what countries and currencies are available to them at any time using the GET List Virtual Account availabilities endpoint.
Account formats
The virtual account details are available in two response parameters:
LocalAccountDetails– An object containing theAddressandAccountdetails in local format, based on the Virtual AccountCountry. Note that the properties of theAccountobject vary depending on theCountry.InternationalAccountDetails– An array of objects containing theAddressandAccountin 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. TheAccountOwneris “MGPPlatformTradingName”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. TheAccountOwneris Natural User’s “FirstNameLastName” 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:
Addressfor a Natural UserLegalRepresentativeAddressfor 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.