​
Description

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

Once created, any funds received on the account are automatically credited to the associated wallet as an External Instruction Bank Wire PayIn. Note therefore that Fees cannot be taken on pay-ins to virtual accounts.

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.

For more information, see the Virtual Account guide.

User-Owned accounts require a contract amendment and activation – contact our teams via the Dashboard to get started.

Note - Replaces legacy Banking Alias feature

The Virtual Account endpoints replace the legacy Banking Alias endpoints, and new integrations should use virtual accounts.

Existing platforms are invited to change their integration to benefit from extended country and currency coverage, as well as any future product improvements.

If a wallet already has a Banking Alias attached, it cannot be used for Virtual Accounts – you need to create a new wallet.

​
Attributes

​
Id
string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

​
Tag
string

Max. length: 255 characters

Custom data that you can add to this object.

​
CreationDate
Unix timestamp

The date and time at which the object was created.

​
WalletId
string

The unique identifier of the wallet.

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

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 “MGP PlatformTradingName”
  • 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.

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

​
Capabilities
object

Information about the account’s payment capabilities.

​
ResultCode
string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

​
ResultMessage
string

The explanation of the result code.

Guide

Learn more about virtual accounts