​
Introduction

Mangopay enables you to create an IBAN attached to a wallet. Once created, any funds wired by the user to that dedicated IBAN 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 IBANs for your users’ wallets. You can also see local and international pay-in capabilities available to your platform.

Caution - Replaces deprecated 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. Existing platforms are invited to change their integration to benefit from extended country and currency coverage.

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

  • 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
  • Adherence to financial market standards (ISO 20022)

Note - Beta release

This beta documentation is designed to allow early-adopting platforms to integrate virtual accounts. The feature is subject to minor changes until public launch.

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

1

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.

2

You create the virtual account

You call the POST Create a Virtual Account endpoint, specifying the country and purpose (see types for details).

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

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:

1

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.

2

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.

3

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.

4

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). PENDING can transition to ACTIVE, FAILED, or BLOCKED.
  • ACTIVE – The account is active and can receive funds. 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:
    • CreditedUserId
    • 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.

​
Endpoints

The following endpoints are available for managing the Virtual Account object:

POST Create a Virtual Account

Set up a virtual IBAN or local account attached to a wallet

PUT Deactivate a Virtual Account

Close an account permanently to prevent it being used

GET View a Virtual Account

See details of a virtual account

GET List Virtual Accounts for a Wallet

See all virtual accounts attached to a wallet

GET View Virtual Account Availabilities

See your platform’s account capabilities per account type and country

​
IBAN countries and currencies

Mangopay offers IBANs for the following countries, specified in the Country parameter of both the Virtual Account object and the deprecated 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 deprecated Banking Alias.

IBAN countryWallet currencyVirtual AccountBanking Alias (deprecated)
AU - AustraliaAUDPlanned
DK - DenmarkDKK
DE - GermanyEUR
ES - Spain
FR - France
LU - Luxembourg
GB - UKGBP
PL - PolandPLNPlannedPlanned

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 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.
  • USER_OWNED – Owned by the wallet owner, enabling them to accept and store funds and make payments. KYC verification is required and the user must be categorized as an Owner.

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 accountUser-owned account
PurposeCollection and reconciliation of funds by the platformUser’s acceptance and storing of funds
Account ownerMangopay S.A. or Mangopay UK Ltd.Wallet owner
Account holder name exampleMangopay S.A (for ACME Corp)Alex Smith
Allowed user categoryOwner or PayerOwner
KYC verificationNot requiredRequired
PayoutsProhibited from the associated wallet, except for refunds returning funds to their originAuthorized from the associated wallet

Note – Both types require user address data

Both types of virtual account 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 virtual account (regardless of whether its VirtualAccountPurpose is COLLECTION or USER_OWNED).

​
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 “Mangopay S.A. (for PlatformTradingName)” or “Mangopay UK Ltd. (for 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.

​
Errors

The following 200 errors may be returned on the virtual accounts feature:

  • 015101 – Unsupported currency
  • 015102 – Invalid country for wallet currency
  • 002703 – User is not an Owner (for USER_OWNED)
  • 002981 – User is not KYC verified (for USER_OWNED)
  • 015201 – Transaction refused due to VirtualAccountPurpose

Was this page helpful?