Create an IBAN Banking Alias

Caution – Replaced by Virtual Accounts

New integrations should use Virtual Accounts, which have replaced Banking Aliases. Existing banking aliases can continue to be used and these endpoints are still supported.

See the Banking Alias object for a comparison.

The OwnerName must match the name of the user owning the wallet (FirstName and LastName for a Natural User, Name for a Legal User).

If Mangopay has provided your platform with a Technical Collection Virtual IBAN for reconciliation purposes, the OwnerName must be “Mangopay S.A.” or “Mangopay S.A. - Your Trading Name”. Please ensure your have confirmed this integration with our teams via the Dashboard.

Note - Payee confirmation in the UK

When the user sets up the payee with their bank, Mangopay UK or Mangopay SA is displayed as the account holder name. You should communicate this to them to avoid confusion.

Path parameters

WalletId · string · required

The unique identifier of the wallet.

Body parameters

OwnerName · string · required

Max. length: 255 characters

The owner of the banking alias. The OwnerName must match the name of the user owning the wallet (FirstName and LastName for a Natural User, Name for a Legal User).

If Mangopay has provided your platform with a Technical Collection Virtual IBAN for reconciliation purposes, the OwnerName must be “Mangopay S.A.” or “Mangopay S.A. - Your Trading Name”. Please ensure your have confirmed this integration with our teams via the Dashboard.

Country · string · required

Allowed values: DE, DK, ES, FR, GB, LU, PL

The country of the banking alias. The country must correspond to the currency of the wallet.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

Responses

200 - FR

OwnerName · string

Max. length: 255 characters

The owner of the banking alias. The OwnerName must match the name of the user owning the wallet (FirstName and LastName for a Natural User, Name for a Legal User).

If Mangopay has provided your platform with a Technical Collection Virtual IBAN for reconciliation purposes, the OwnerName must be “Mangopay S.A.” or “Mangopay S.A. - Your Trading Name”. Please ensure your have confirmed this integration with our teams via the Dashboard.

IBAN · string

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

BIC · string

The BIC (international identifier of the bank) for the banking alias.

CreditedUserId · string

The unique identifier of the user whose wallet is credited, in other words, the Owner of the wallet for which the alias is created.
Note: Once the banking alias is created, it is not possible to change the CreditedUserId.

Country · string

Returned values: DE, DK, ES, FR, GB, LU, PL

The country of the banking alias. The country must correspond to the currency of the wallet.

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.

Active · boolean

Whether or not the banking alias is active.

Caution: Setting this value to false is irreversible.

Type · string

Returned values: IBAN, GB

The type of banking alias.

The GB value is only returned if the Country is GB.

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

WalletId · string

The unique identifier of the wallet.

200 - GB

OwnerName · string

Max. length: 255 characters

The owner of the banking alias. The OwnerName must match the name of the user owning the wallet (FirstName and LastName for a Natural User, Name for a Legal User).

If Mangopay has provided your platform with a Technical Collection Virtual IBAN for reconciliation purposes, the OwnerName must be “Mangopay S.A.” or “Mangopay S.A. - Your Trading Name”. Please ensure your have confirmed this integration with our teams via the Dashboard.

IBAN · string

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

BIC · string

The BIC (international identifier of the bank) for the banking alias.

LocalAccountDetails · object

The banking alias details in local format returned if applicable for the Country (e.g. GB), otherwise null

Show child attributes

SortCode · string

The sort code of the banking alias in local format.

AccountNumber · string

The account number of the banking alias in local format.

CreditedUserId · string

The unique identifier of the user whose wallet is credited, in other words, the Owner of the wallet for which the alias is created.
Note: Once the banking alias is created, it is not possible to change the CreditedUserId.

Country · string

Returned values: DE, DK, ES, FR, GB, LU, PL

The country of the banking alias. The country must correspond to the currency of the wallet.

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.

Active · boolean

Whether or not the banking alias is active.

Caution: Setting this value to false is irreversible.

Type · string

Returned values: IBAN, GB

The type of banking alias.

The GB value is only returned if the Country is GB.

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

WalletId · string

The unique identifier of the wallet.

400 - Country not supported

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "fd020620-8e5c-4b64-925c-aa980e42c237#1670340996",
    "Date": 1670340997.0,
    "errors": {
        "Country": "The requested country is not supported"
    }
}

400 - Wallet already has a Banking Alias

{
    "Message": "There is already a banking alias existing for this wallet",
    "Type": "wallet_banking_alias_already_exists",
    "Id": "77b73aa3-e08e-4e04-9ffd-5c94ed4f73ff",
    "Date": 1732178114,
    "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
}

403 - Feature not activated

{
    "Message": "This endpoint is not available for your account",
    "Type": "forbidden_ressource",
    "Id": "441d156a-ebd1-421e-851b-460a25c6a53f#1670262779",
    "Date": 1670262780.0,
    "errors": null
}  

200 - FR

{
    "OwnerName": "Alex Smith",
    "IBAN": "FR7674521100005657670994474",
    "BIC": "MPAYFRP1PIN",
    "CreditedUserId": "user_m_01HSB23417BFG7YXR7E371JSEA",
    "Country": "FR",
    "Tag": "Created using Mangopay API Postman Collection",
    "CreationDate": 1710846581,
    "Active": true,
    "Type": "IBAN",
    "Id": "wltbank_m_01HSB6E769Y3ZBYDJACSP3THGA",
    "WalletId": "wlt_m_01HSB6DE1YT1EMTH0K7ASYPG96"
}

REST

{
    "OwnerName": "Alex Smith",
    "Country": "FR",
    "Tag": "Created using Mangopay API Postman Collection"
}