Skip to main content
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"
}
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_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

​
Id
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.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.
{
    "Message": "This endpoint is not available for your account",
    "Type": "forbidden_ressource",
    "Id": "99e6af46-92d3-4d60-b270-aa0b66c8202b",
    "Date": 1756886350.0,
    "errors": null
}

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

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

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

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

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

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

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

{
    "Id": "7081ae37-f4b2-4c38-9bc4-9a14546d544f",
    "Message": "The user is not KYC-validated",
    "Type": "forbidden_ressource",
    "Date": 1743678181.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"
}