Overview
User management
- Users
- User regulatory status
- User e-money
User verification
- User data format
- KYC documents
- UBO declarations
Wallets
- User wallets
- Client wallets
Cards
- Card registrations
- Cards
- Metadata
- Card validations
Card pay-ins
- Direct card pay-ins
- Recurring card pay-ins
- Preauthorizations
- Deposit preauthorizations
- Web card pay-ins
Banking pay-ins
- Bank wires
- Pay by bank
- Virtual IBAN
- Direct debits
- Web direct debits
APM pay-ins
- Apple Pay
- Bancontact
- BLIK
- Giropay
- Google Pay
- iDEAL
- Klarna
- MB WAY
- Multibanco
- Payconiq
- PayPal
- Satispay
- Swish
- TWINT
Transfers
- Transfers
Refunds
- Refunds
Disputes
- Disputes
- Dispute documents
- Repudiations
- Dispute settlement
Payouts
- Recipients
- Bank accounts
- Payouts
FX conversions
- Conversion rates
- Quotes
- Conversions
Transactions
- Transactions
Helpers
- API responses
- Country authorizations
- Webhooks
- Events
- Reports
Platform account
- Client
- Dashboard permissions
Create a Virtual Account
Set up a virtual IBAN or local account attached to a wallet
{
"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 PLATFORM NAME",
"LocalAccountDetails": {
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"SortCode": "608382",
"AccountNumber": "23356198"
}
},
"InternationalAccountDetails": [
{
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"Iban": "GB79SAPY60838223356198",
"Bic": "SAPYGB2L"
}
}
],
"Capabilities": {
"LocalPayinAvailable": true,
"InternationalPayinAvailable": true,
"Currencies": [
"GBP"
]
},
"ResultCode": "000000",
"ResultMessage": "Success"
}
Path parameter
The unique identifier of the wallet.
Body parameters
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.
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.
Max. length: 255 characters
Custom data that you can add to this object.
Responses
The unique identifier of the object.
Max. length: 255 characters
Custom data that you can add to this object.
The date and time at which the object was created.
The unique identifier of the wallet.
The unique identifier of the user whose wallet is credited.
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.
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.
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).PENDINGcan transition toACTIVEorFAILED.ACTIVE– The account is active and can receive funds (see note about delayed UK CoP recognition forGBaccounts).ACTIVEcan transition toBLOCKEDorCLOSED.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.BLOCKEDcan transition toACTIVEorCLOSED.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.
Whether or not the Virtual Account is active.
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 “MGPPlatformTradingName”USER_OWNED– Owned by the owner of the associated wallet:FirstNameLastNamefor Natural Users;Namefor Legal Users
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.
The address associated with the account.
Max. length: 255 characters
The building number and street name of the address.
Max. length: 50 characters
The postal code of the address.
Max. length: 255 characters
The town or city of the address.
Max. length: 255 characters
The region, state, or county of the address.
Format: Two-letter country code (ISO 3166-1 alpha-2 format)
The country of the address.
Details of the account in local account identifier format.
The properties of this object differ depending on the Virtual Account Country:
- IBAN – Format if
CountryisDK,DE,ES,FR,LU - GB – Format if
CountryisGB
Caution: Other formats are planned in future as Mangopay’s account coverage expands. Ensure you retrieve the Account object’s properties and values dynamically.
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.
The address associated with the account.
Max. length: 255 characters
The building number and street name of the address.
Max. length: 50 characters
The postal code of the address.
Max. length: 255 characters
The town or city of the address.
Max. length: 255 characters
The region, state, or county of the address.
Format: Two-letter country code (ISO 3166-1 alpha-2 format)
The country of the address.
Information about the account’s payment capabilities.
Whether or not local bank wires can be made to this account.
Whether or not international bank wires can be made to this account.
The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.
The explanation of the result code.
{
"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": "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 PLATFORM NAME",
"LocalAccountDetails": {
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"SortCode": "608382",
"AccountNumber": "23356198"
}
},
"InternationalAccountDetails": [
{
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"Iban": "GB79SAPY60838223356198",
"Bic": "SAPYGB2L"
}
}
],
"Capabilities": {
"LocalPayinAvailable": true,
"InternationalPayinAvailable": true,
"Currencies": [
"GBP"
]
},
"ResultCode": "000000",
"ResultMessage": "Success"
}
{
"Country": "GB",
"VirtualAccountPurpose": "COLLECTION",
"Tag": "Created using Mangopay API Postman Collection"
}
Was this page helpful?
{
"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 PLATFORM NAME",
"LocalAccountDetails": {
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"SortCode": "608382",
"AccountNumber": "23356198"
}
},
"InternationalAccountDetails": [
{
"Address": {
"StreetName": "2, Avenue Amélie",
"PostCode": "L-1125",
"TownName": "Luxembourg",
"CountrySubDivision": null,
"Country": "LU"
},
"Account": {
"Iban": "GB79SAPY60838223356198",
"Bic": "SAPYGB2L"
}
}
],
"Capabilities": {
"LocalPayinAvailable": true,
"InternationalPayinAvailable": true,
"Currencies": [
"GBP"
]
},
"ResultCode": "000000",
"ResultMessage": "Success"
}