Create a Virtual Account

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

Virtual Account object →

Path parameter

WalletId · string · required

The unique identifier of the wallet.

Body parameters

Country · string · required

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

VirtualAccountPurpose · string · required

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.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

Responses

200

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.

Show child attributes

Address · object

The address associated with the account.

Show child attributes

StreetName · string

Max. length: 255 characters

The building number and street name of the address.

PostCode · string

Max. length: 50 characters

The postal code of the address.

TownName · string

Max. length: 255 characters

The town or city of the address.

CountrySubDivision · string

Max. length: 255 characters

The region, state, or county of the address.

Country · string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

Account · object | null

Details of the account in local account identifier format.

The properties of this object differ depending on the Virtual Account Country:

• IBAN – Format if Country is DK, DE, ES, FR, LU
• GB – Format if Country is GB
• US – Format if Country is US
• CA – Format if Country is CA

Caution: Other formats are planned in future as Mangopay’s account coverage expands. Ensure you retrieve the Account object’s properties and values dynamically.

IBAN

Hide properties

IBAN · string

The international bank account number (IBAN) of the account.

BIC · string

The bank identifier code (BIC) of the account.

Hide properties

IBAN · string

The international bank account number (IBAN) of the account.

BIC · string

The bank identifier code (BIC) of the account.

Hide properties

AccountNumber · string

The account number of the account.

SortCode · string

The sort code of the account.

Hide properties

AccountNumber · string

The account number of the account.

AchNumber · string

The 9-digit ACH routing number of the US account.

FedWireNumber · string

The 9-digit Fedwire (ABA) number of the US account.

AccountType · string

The account type of the US account, which is always CHECKING.

Hide properties

BranchCode · string

The 5-digit branch code or transit number of the CA account.

InstitutionNumber · string

The 3-digit institution number of the CA account.

AccountNumber · string

The account number of the account.

BankName · string | null

The name of the bank.

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.

Show child attributes

Address · object

The address associated with the account.

Show child attributes

StreetName · string

Max. length: 255 characters

The building number and street name of the address.

PostCode · string

Max. length: 50 characters

The postal code of the address.

TownName · string

Max. length: 255 characters

The town or city of the address.

CountrySubDivision · string

Max. length: 255 characters

The region, state, or county of the address.

Country · string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

Account · object | null

Details of the account in international format.

Returned null if Country is US or CA as Capabilities.InternationalPayinAvailable is always false.

Show child attributes

IBAN · string

The international bank account number (IBAN) of the account.

BIC · string

The bank identifier code (BIC) of the account.

BankName · string | null

The name of the bank.

Capabilities · object

Information about the account’s payment capabilities.

Show child attributes

LocalPayinAvailable · boolean

Whether or not local bank wires can be made to this account.

InternationalPayinAvailable · boolean

Whether or not international bank wires can be made to this account.

Returned false if Country is US or CA.

Currencies · array

Returned values: One or more currency codes in ISO 4217 format (EUR, GBP, etc.)

List of currencies supported by the account.

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.

400 - Currency not supported

{
    "Message": "Wallet currency not supported. Supported values: EUR/GBP/AUD/DKK/PLN.",
    "Type": "wallet_currency_not_supported",
    "Id": "1eb1c947-bac2-4127-a636-fe7d811db9e7",
    "Date": 1725288513.0,
    "errors": null
}

400 - Invalid country for wallet currency

{
    "Message": "Invalid country GB for EUR wallet. Possible value(s): LU/FR/ES/DE.",
    "Type": "country_not_associated_to_wallet_currency",
    "Id": "1eb1c947-bac2-4127-a636-fe7d811db9e7",
    "Date": 1725288513.0,
    "errors": null
}

400 - Only one purpose per wallet

{
    "Message": "The wallet already has an associated Collection Virtual Account",
    "Type": "incorrect_account_purpose_for_wallet",
    "Id": "d29c77bc-e670-4c72-a715-445489532a1a",
    "Date": 1726238248,
    "errors": null
}

{
    "Message": "The wallet already has an associated User Owned Virtual Account",
    "Type": "incorrect_account_purpose_for_wallet",
    "Id": "8095b0a1-b00b-4696-b5f1-e716c3671707",
    "Date": 1726238338,
    "errors": null
}

400 - Banking alias already exists

{
    "Id": "f577f4c5-3175-4023-b97a-8f5af47fdbff",
    "Message": "There is already a banking alias existing for this wallet",
    "Type": "wallet_banking_alias_already_exists",
    "Date": 1743678181.0,
    "errors": null
}

400 - Address required for User-Owned

{
    "Id": "19987822-6cd1-4dd8-8b83-8cfdda49bcb2",
    "Message": "Missing field in Address for USER_OWNED account purpose",
    "Type": "user_error",
    "Date": 1743678181.0,
    "errors": null
}

403 - User-Owned only allowed if user's UserCategory is OWNER

{
    "Id": "b8449773-2fe3-4fee-87f3-c8c84dc574ea",
    "Message": "Refused due to user UserCategory: PAYER",
    "Type": "forbidden_ressource",
    "Date": 1743678181.0,
    "errors": null
}

403 - User-Owned only allowed if user's KYCLevel is REGULAR

{
    "Id": "7081ae37-f4b2-4c38-9bc4-9a14546d544f",
    "Message": "The user is not KYC-validated",
    "Type": "forbidden_ressource",
    "Date": 1743678181.0,
    "errors": null
}

GB - ACTIVE

{
    "Id": "wltbank_01JSH9TKTHE2KHXENE8K4KD46C",
    "Tag": "Created using Mangopay API Postman Collection",
    "CreationDate": 1745411198,
    "WalletId": "wlt_m_01JSH9TDQHSMZX5GDV6TSM9SYN",
    "VirtualAccountPurpose": "COLLECTION",
    "Country": "GB",
    "Active": true,
    "Status": "ACTIVE",
    "AccountOwner": "MGP PlatformTradingName",
    "LocalAccountDetails": {
        "Address": {
            "StreetName": "68 King William Street",
            "PostCode": "EC4N 7HR",
            "TownName": "London",
            "CountrySubDivision": null,
            "Country": "GB"
        },
        "Account": {
            "SortCode": "608382",
            "AccountNumber": "22276063"
        },
        "BankName": "Banking Circle S.A. UK Branch"
    },
    "InternationalAccountDetails": [
        {
            "Address": {
                "StreetName": "68 King William Street",
                "PostCode": "EC4N 7HR",
                "TownName": "London",
                "CountrySubDivision": null,
                "Country": "GB"
            },
            "Account": {
              "Iban": "GB92SAPY60838222276063",
                "Bic": "SAPYGB2L"
            },
            "BankName": "Banking Circle S.A. UK Branch"
        }
    ],
    "Capabilities": {
        "LocalPayinAvailable": true,
        "InternationalPayinAvailable": true,
        "Currencies": [
            "GBP"
        ]
    },
    "ResultCode": "000000",
    "ResultMessage": "Success"
}

REST

{
    "Country": "GB",
    "VirtualAccountPurpose": "COLLECTION",
    "Tag": "Created using Mangopay API Postman Collection"
}