Create a Virtual Account

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

{
    "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"
}

POST

v2.01

{ClientId}

wallets

{WalletId}

virtual-accounts

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

{
    "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"
}

Note – One account purpose per walletA wallet can only have either COLLECTION or USED_OWNED virtual accounts attached, but not both.It is, however, possible to attach multiple virtual accounts of the same VirtualAccountPurpose to a single wallet.

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_OWNEDThe 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. Offering User-Owned Accounts requires your platform to sign the VOP contract amendment.

For more information, see the virtual account guide.

Tag

string

Max. length: 255 charactersCustom data that you can add to this object.

Responses

200

string

Max length: 128 characters (see data formats for details)The unique identifier of the object.

Tag

string

Max. length: 255 charactersCustom 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

Returned values: COLLECTION, USER_OWNEDThe 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. Offering User-Owned Accounts requires your platform to sign the VOP contract amendment.

For more information, see the 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, populated if Capabilities.LocalPayinAvailable is true.Caution: Retrieve both the fields and values of these child objects dynamically to present to the user. The LocalAccountDetails.Account object has different properties depending on the virtual account Country, and these may change over time as Mangopay’s coverage expands.

Show child attributes

Address

object

The address associated with the account.

Show child attributes

StreetName

string

Max. length: 255 charactersThe building number and street name of the address.

PostCode

string

Max. length: 50 charactersThe postal code of the address.

TownName

string

Max. length: 255 charactersThe town or city of the address.

CountrySubDivision

string

Max. length: 255 charactersThe 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 DE, ES, FR, LU
DK – Format if Country is DK
GB – Format if Country is GB
US – Format if Country is US
CA – Format if Country is CA
AU – Format if Country is AU
LI – Format if Country is LI

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

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.

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.

BankName

string | null

The name of the bank.

InternationalAccountDetails

array (object)

List of the account details in international format, populated if Capabilities.InternationalPayinAvailable is true.Best practice: Retrieve both the fields and values of these child objects dynamically to present to the user. The InternationalAccountDetails.Account object may be null 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 charactersThe building number and street name of the address.

PostCode

string

Max. length: 50 charactersThe postal code of the address.

TownName

string

Max. length: 255 charactersThe town or city of the address.

CountrySubDivision

string

Max. length: 255 charactersThe 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, CA, or AU as Capabilities.InternationalPayinAvailable is false for these countries.

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.

403 - Collection accounts not activated

{
    "Message": "This endpoint is not available for your account",
    "Type": "forbidden_ressource",
    "Id": "99e6af46-92d3-4d60-b270-aa0b66c8202b",
    "Date": 1756886350.0,
    "errors": null
}

403 - User-Owned accounts not activated

{
    "Message": "User Owned Accounts are not enabled. Contact your support to activate this feature.",
    "Type": "forbidden_ressource",
    "Id": "f2ca7774-4e64-4b84-9320-06d2da387505",
    "Date": 1756886422.0,
    "errors": null
}

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
}

400 - User-Owned only allowed if user has UBO

{
    "Message": "Missing wallet owner UBO details",
    "Type": "user_error",
    "Id": "f986c025-6734-4b76-bbb8-6ae0eff743a3",
    "Date": 1771850580.0,
    "errors": null
}

{
    "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"
}

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

View Virtual Account availabilities Deactivate a Virtual Account

⌘I

Documentation Index

​Path parameter

​Body parameters

​Responses

Path parameter

Body parameters

Responses