​
Description

The Virtual Account object enables platforms to attached one or more virtual IBANs to a wallet.

There are two types of Virtual Account, indicated by the VirtualAccountPurpose:

  • 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.

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.

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.

For more information, see the Virtual Account guide.

​
Attributes

​
Id
string

The unique identifier of the object.

​
Tag
string

Max. length: 255 characters

Custom data that you can add to this object.

​
CreationDate
timestamp

The date and time at which the object was created.

​
WalletId
string

The unique identifier of the wallet.

​
CreditedUserId
string

The unique identifier of the user whose wallet is credited.

​
VirtualAccountPurpose
string

Allowed values: COLLECTION, USER_OWNED

The type of the virtual account:

  • COLLECTION - Owned by Mangopay and usable by platforms and/or users for the purpose of collecting and reconciling incoming funds paid by users.
  • USER_OWNED - Owned by the wallet owner, enabling them to accept and store funds and make payments.

For more information, see virtual account guide.

​
Country
string

Returned values: The two-letter ISO 3166-1 country code (LU, FR, GB, etc.) of an available country (depends on contract and activation settings).

The country of the IBAN. The country must correspond to the currency of the wallet. See the virtual account guide for details.

​
Status
string

The status of the Virtual Account:

  • 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).

See the virtual account guide for more details.

​
Active
boolean

Whether or not the Virtual Account is active.

​
AccountOwner
string

The owner of the virtual account.

The account owner is assigned automatically depending on the VirtualAccountPurpose:

  • COLLECTION – Owned by Mangopay SA or Mangopay UK Ltd., mentioning the platform’s trading name in the format “Mangopay SA (for Your Trading Name)”
  • USER_OWNED – Owned by the owner of the associated wallet: FirstName LastName for Natural Users; Name for Legal Users
​
LocalAccountDetails
object

The account details in local format.

Best practice: Retrieve both the fields and values of these objects dynamically to present to the user. The LocalAccountDetails.Account object has different properties depending on the virtual account Country.

​
InternationalAccountDetails
array (object)

List of the account details in international format.

Note: The InternationalAccountDetails.Account is returned in IBAN and BIC format, but it is possible that the properties of these objects vary in future so you should retrieve both the fields and values dynamically.

​
Capabilities
object

Information about the account’s payment capabilities.

Guide

Learn more about virtual accounts

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

Was this page helpful?