Create a Virtual Account

POST

/v2.01/:ClientId/wallets/:WalletId/virtual-accounts

POST

/v2.01/:ClientId/wallets/:WalletId/virtual-accounts

$ curl -X POST https://api.sandbox.mangopay.com/v2.01/ClientId/wallets/WalletId/virtual-accounts \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "body": {
>     "Country": "GB",
>     "VirtualAccountPurpose": "COLLECTION",
>     "Tag": "Created using Mangopay API Postman Collection"
>   }
> }'

1 {
2   "Id": "wltbank_01JSH9TKTHE2KHXENE8K4KD46C",
3   "Tag": "Created using Mangopay API Postman Collection",
4   "CreationDate": 1745411198,
5   "WalletId": "wlt_m_01JSH9TDQHSMZX5GDV6TSM9SYN",
6   "VirtualAccountPurpose": "COLLECTION",
7   "Country": "GB",
8   "Active": true,
9   "Status": "ACTIVE",
10   "AccountOwner": "MGP PlatformTradingName",
11   "LocalAccountDetails": {
12     "Address": {
13       "StreetName": "68 King William Street",
14       "PostCode": "EC4N 7HR",
15       "TownName": "London",
16       "CountrySubDivision": null,
17       "Country": "GB"
18     },
19     "Account": {
20       "SortCode": "608382",
21       "AccountNumber": "22276063"
22     },
23     "BankName": "Banking Circle S.A. UK Branch"
24   },
25   "InternationalAccountDetails": [
26     {
27       "Address": {
28         "StreetName": "68 King William Street",
29         "PostCode": "EC4N 7HR",
30         "TownName": "London",
31         "CountrySubDivision": null,
32         "Country": "GB"
33       },
34       "Account": {
35         "Iban": "GB92SAPY60838222276063",
36         "Bic": "SAPYGB2L"
37       },
38       "BankName": "Banking Circle S.A. UK Branch"
39     }
40   ],
41   "Capabilities": {
42     "LocalPayinAvailable": true,
43     "InternationalPayinAvailable": true,
44     "Currencies": [
45       "GBP"
46     ]
47   },
48   "ResultCode": "000000",
49   "ResultMessage": "Success"
50 }

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

Note – One account purpose per wallet

A wallet can only have either COLLECTION or USER_OWNED virtual accounts attached, but not both.

It is, however, possible to attach multiple virtual accounts of the same VirtualAccountPurpose to a single wallet.

Set up a virtual IBAN or local account attached to a wallet <Note icon="fa-regular fa-circle-info"> **Note – One account purpose per wallet** A wallet can only have either `COLLECTION` or `USER_OWNED` virtual accounts attached, but not both. It is, however, possible to attach multiple virtual accounts of the same `VirtualAccountPurpose` to a single wallet. </Note>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

If your platform is using a proxy to take SCA-triggering action on behalf of users, you also need to integrate mTLS authentication and use the api-mtls base URL.

Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

Path parameters

ClientIdstringRequired

Platform's API account identifier, associated with the API key.

WalletIdstringRequired

Request

This endpoint expects an object.

CountrystringRequired

Allowed values: The two-letter ISO 3166-1 country code (LU, FR, GB, etc.) of an available country (depends on contract and activation settings): AU, CA, DK, DE, ES, FR, GB, LI, LU, US

The country of the Virtual Account. The country must correspond to the currency of the wallet. See the virtual account guide for details.

VirtualAccountPurposestringRequired

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

For more information, see the virtual account guide.

TagstringOptional

Max. length: 255 characters

Custom data that you can add to this object.

Response

Success

AUobject

Australian Virtual Account with Country AU.

LocalAccountDetails.Account uses the AU-specific format (BSBCode, AccountNumber).

InternationalAccountDetails is always null because Capabilities.InternationalPayinAvailable is always false.

CAobject

Canadian Virtual Account with Country CA.

LocalAccountDetails.Account uses the CA-specific format (BranchCode, InstitutionNumber, AccountNumber).

InternationalAccountDetails is always null because Capabilities.InternationalPayinAvailable is always false.

DEobject

German Virtual Account with Country DE.

LocalAccountDetails.Account uses the IBAN format.

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

DKobject

Danish Virtual Account with Country DK.

LocalAccountDetails.Account uses the DK-specific format (BankCode, AccountNumber).

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

ESobject

Spanish Virtual Account with Country ES.

LocalAccountDetails.Account uses the IBAN format.

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

FRobject

French Virtual Account with Country FR.

LocalAccountDetails.Account uses the IBAN format.

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

GBobject

United Kingdom (UK) Virtual Account with Country GB.

LocalAccountDetails.Account uses the GB-specific format (AccountNumber, SortCode).

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

LIobject

Liechtenstein Virtual Account with Country LI.

LocalAccountDetails.Account uses the LI-specific format (BCNumber, AccountNumber).

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true. For LI, InternationalAccountDetails.Account uses the same format as LocalAccountDetails.Account.

LUobject

Luxembourg Virtual Account with Country LU.

LocalAccountDetails.Account uses the IBAN format.

InternationalAccountDetails is populated if Capabilities.InternationalPayinAvailable is true.

USobject

United States Virtual Account with Country US.

LocalAccountDetails.Account uses the US-specific format (AccountNumber, AchNumber, FedWireNumber, AccountType).

InternationalAccountDetails is always null because Capabilities.InternationalPayinAvailable is always false.

Errors

400

Bad Request Error

403

Forbidden Error