Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Reference Banking Aliases API
version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
description: Sandbox
- url: https://api.mangopay.com
description: Production
- url: https://api-mtls.sandbox.mangopay.com
description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.
**Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.
'
tags:
- name: bankingAliases
paths:
/v2.01/{ClientId}/wallets/{WalletId}/bankingaliases/iban:
post:
operationId: bankingAliases_create_iban_banking_alias
summary: Create an IBAN Banking Alias
description: '**Deprecated – Decommissioning planned for 2027**
Mangopay plans to decommission the Banking Alias endpoints in 2027.
Platforms using them should plan to re-integrate using the Virtual Account endpoints.
Existing Banking Alias objects are available via the GET View a Virtual Account endpoint by using the Banking Alias `Id` and `WalletId` as path parameters.
**Caution – Rely on `OwnerName` returned in response**
Since September 15, 2025, Mangopay sets the `OwnerName` value by default based on the criteria available here.
Your platform must rely on the API response value (also available on the GET endpoints) and ensure it is easy to see and copy for the end user in your interfaces.
**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.
Create an IBAN Banking Alias'
tags:
- bankingAliases
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: WalletId
in: path
description: The unique identifier of the wallet.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnIBANBankingAliasResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnIBANBankingAliasRequest'
security:
- oauth2: []
/v2.01/{ClientId}/bankingaliases/{BankingAliasId}:
put:
operationId: bankingAliases_deactivate_banking_alias
summary: Deactivate a Banking Alias
description: '**Deprecated – Decommissioning planned for 2027**
Mangopay plans to decommission the Banking Alias endpoints in 2027.
Platforms using them should plan to re-integrate using the Virtual Account endpoints.
Existing Banking Alias objects are available via the GET View a Virtual Account endpoint by using the Banking Alias `Id` and `WalletId` as path parameters.
**Caution – Deactivating a Banking Alias is irreversible**
Once the Banking Alias object is deactivated, you cannot reactivate it or attach another to the same wallet.
Any funds wired to the banking alias won''t be credited to the corresponding wallet.
If such cases arise, contact Mangopay via the Dashboard.
Deactivate a Banking Alias'
tags:
- bankingAliases
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: BankingAliasId
in: path
description: The unique identifier of the banking alias.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateABankingAliasResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateABankingAliasRequest'
security:
- oauth2: []
get:
operationId: bankingAliases_view_banking_alias
summary: View a Banking Alias
description: '**Deprecated – Decommissioning planned for 2027**
Mangopay plans to decommission the Banking Alias endpoints in 2027.
Platforms using them should plan to re-integrate using the Virtual Account endpoints.
Existing Banking Alias objects are available via the GET View a Virtual Account endpoint by using the Banking Alias `Id` and `WalletId` as path parameters.
**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.
View a Banking Alias'
tags:
- bankingAliases
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: BankingAliasId
in: path
description: The unique identifier of the banking alias.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ViewABankingAliasResponse'
security:
- oauth2: []
/v2.01/{ClientId}/wallets/{WalletId}/bankingaliases:
get:
operationId: bankingAliases_view_banking_alias_wallet
summary: View a Banking Alias for a Wallet
description: '**Deprecated – Decommissioning planned for 2027**
Mangopay plans to decommission the Banking Alias endpoints in 2027.
Platforms using them should plan to re-integrate using the Virtual Account endpoints.
Existing Banking Alias objects are available via the GET View a Virtual Account endpoint by using the Banking Alias `Id` and `WalletId` as path parameters.
**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.
View a Banking Alias for a Wallet'
tags:
- bankingAliases
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: WalletId
in: path
description: The unique identifier of the wallet.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ViewABankingAliasForAWalletResponse'
security:
- oauth2: []
components:
schemas:
DeactivateABankingAliasRequest:
type: object
properties:
Active:
type: boolean
description: 'Whether or not the banking alias is active.
**Caution:** Setting this value to `false` is irreversible.'
required:
- Active
title: DeactivateABankingAliasRequest
CreateAnIBANBankingAliasRequest:
type: object
properties:
OwnerName:
type: string
description: The owner of the banking alias, which is set automatically by Mangopay since September 15, 2025 ([read more](/guides/vop/payins#banking-alias-categorization)). If the User owning the attached wallet has `UserCategory` of `OWNER` and the `KYCLevel` of `REGULAR`, then the `OwnerName` is set to the `FirstName` and `LastName` values for a [Natural User](/api-reference/users/natural-user-object-sca) or the `Name` value for a [Legal User](/api-reference/users/legal-user-object-sca). In this case, the `VirtualAccountPurpose` in the API response is `USER_OWNED` . If the User is not KYC verified and an `OWNER`, then the `OwnerName` is set to “MGP `PlatformTradingName`" in standard cases, or else “Mangopay” for Marketplace Payment Extension (MPE) workflows. In this case, the `VirtualAccountPurpose` in the API response is `COLLECTION`. **Caution:** Your platform must ensure that you use the `OwnerName` returned in the API response.
Country:
type: string
description: '**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:
$ref: '#/components/schemas/Tag'
required:
- OwnerName
- Country
title: CreateAnIBANBankingAliasRequest
Id:
type: string
description: 'Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.'
title: Id
ViewABankingAliasForAWalletResponseArrayBankingAliasItemsObjectBankingAlias:
type: object
properties:
OwnerName:
type: string
description: The owner of the banking alias, which is set automatically by Mangopay since September 15, 2025 ([read more](/guides/vop/payins#banking-alias-categorization)). If the User owning the attached wallet has `UserCategory` of `OWNER` and the `KYCLevel` of `REGULAR`, then the `OwnerName` is set to the `FirstName` and `LastName` values for a [Natural User](/api-reference/users/natural-user-object-sca) or the `Name` value for a [Legal User](/api-reference/users/legal-user-object-sca). In this case, the `VirtualAccountPurpose` in the API response is `USER_OWNED`. If the User is not KYC verified and an `OWNER`, then the `OwnerName` is set to “MGP `PlatformTradingName`" in standard cases, or else “Mangopay” for Marketplace Payment Extension (MPE) workflows. In this case, the `VirtualAccountPurpose` in the API response is `COLLECTION`. **Caution:** Your platform must ensure that you use the `OwnerName` returned in the API response.
IBAN:
type: string
description: The IBAN (international bank account number) of the banking alias.
BIC:
type: string
description: The BIC (international identifier of the bank) for the banking alias.
VirtualAccountPurpose:
type: string
description: '**Returned 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](/guides/vop) contract amendment.
For more information, see the [virtual account](/guides/payment-methods/banking/virtual-iban) guide.'
LocalAccountDetails:
$ref: '#/components/schemas/SortCodeAccountNumber'
CreditedUserId:
type: string
description: '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:
type: string
description: '**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:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
Active:
type: boolean
description: 'Whether or not the banking alias is active.
**Caution:** Setting this value to `false` is irreversible.'
Type:
type: string
description: '**Returned values:** `IBAN`, `GB`
The type of banking alias.
The `GB` value is only returned if the `Country` is `GB`.'
Id:
$ref: '#/components/schemas/Id'
WalletId:
type: string
description: The unique identifier of the wallet.
description: The Banking Alias object created by the platform.
title: ViewABankingAliasForAWalletResponseArrayBankingAliasItemsObjectBankingAlias
ViewABankingAliasResponse:
type: object
properties:
OwnerName:
type: string
description: The owner of the banking alias, which is set automatically by Mangopay since September 15, 2025 ([read more](/guides/vop/payins#banking-alias-categorization)). If the User owning the attached wallet has `UserCategory` of `OWNER` and the `KYCLevel` of `REGULAR`, then the `OwnerName` is set to the `FirstName` and `LastName` values for a [Natural User](/api-reference/users/natural-user-object-sca) or the `Name` value for a [Legal User](/api-reference/users/legal-user-object-sca). In this case, the `VirtualAccountPurpose` in the API response is `USER_OWNED`. If the User is not KYC verified and an `OWNER`, then the `OwnerName` is set to “MGP `PlatformTradingName`" in standard cases, or else “Mangopay” for Marketplace Payment Extension (MPE) workflows. In this case, the `VirtualAccountPurpose` in the API response is `COLLECTION`. **Caution:** Your platform must ensure that you use the `OwnerName` returned in the API response.
IBAN:
type: string
description: The IBAN (international bank account number) of the banking alias.
BIC:
type: string
description: The BIC (international identifier of the bank) for the banking alias.
VirtualAccountPurpose:
type: string
description: '**Returned 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](/guides/vop) contract amendment.
For more information, see the [virtual account](/guides/payment-methods/banking/virtual-iban) guide.'
CreditedUserId:
type: string
description: '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:
type: string
description: '**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:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
Active:
type: boolean
description: 'Whether or not the banking alias is active.
**Caution:** Setting this value to `false` is irreversible.'
Type:
type: string
description: '**Returned values:** `IBAN`, `GB`
The type of banking alias.
The `GB` value is only returned if the `Country` is `GB`.'
Id:
$ref: '#/components/schemas/Id'
WalletId:
type: string
description: The unique identifier of the wallet.
LocalAccountDetails:
$ref: '#/components/schemas/SortCodeAccountNumber'
title: ViewABankingAliasResponse
SortCodeAccountNumber:
type: object
properties:
SortCode:
type: string
description: The sort code of the banking alias in local format.
AccountNumber:
type: string
description: The account number of the banking alias in local format.
description: The banking alias details in local format returned if applicable for the `Country` (e.g. `GB`), otherwise `null`
title: SortCodeAccountNumber
ViewABankingAliasForAWalletResponse:
type: object
properties:
Array (Banking Alias):
type: array
items:
$ref: '#/components/schemas/ViewABankingAliasForAWalletResponseArrayBankingAliasItems'
description: The list of banking aliases created by the platform.
title: ViewABankingAliasForAWalletResponse
Tag:
type: string
description: 'Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.'
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
DeactivateABankingAliasResponse:
type: object
properties:
OwnerName:
type: string
description: The owner of the banking alias, which is set automatically by Mangopay since September 15, 2025 ([read more](/guides/vop/payins#banking-alias-categorization)). If the User owning the attached wallet has `UserCategory` of `OWNER` and the `KYCLevel` of `REGULAR`, then the `OwnerName` is set to the `FirstName` and `LastName` values for a [Natural User](/api-reference/users/natural-user-object-sca) or the `Name` value for a [Legal User](/api-reference/users/legal-user-object-sca). In this case, the `VirtualAccountPurpose` in the API response is `USER_OWNED`. If the User is not KYC verified and an `OWNER`, then the `OwnerName` is set to “MGP `PlatformTradingName`" in standard cases, or else “Mangopay” for Marketplace Payment Extension (MPE) workflows. In this case, the `VirtualAccountPurpose` in the API response is `COLLECTION`. **Caution:** Your platform must ensure that you use the `OwnerName` returned in the API response.
IBAN:
type: string
description: The IBAN (international bank account number) of the banking alias.
BIC:
type: string
description: The BIC (international identifier of the bank) for the banking alias.
CreditedUserId:
type: string
description: '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:
type: string
description: '**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:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
Active:
type: boolean
description: 'Whether or not the banking alias is active.
**Caution:** Setting this value to `false` is irreversible.'
Type:
type: string
description: '**Returned values:** `IBAN`, `GB`
The type of banking alias.
The `GB` value is only returned if the `Country` is `GB`.'
Id:
$ref: '#/components/schemas/Id'
WalletId:
type: string
description: The unique identifier of the wallet.
title: DeactivateABankingAliasResponse
CreateAnIBANBankingAliasResponse:
type: object
properties:
OwnerName:
type: string
description: The owner of the banking alias, which is set automatically by Mangopay since September 15, 2025 ([read more](/guides/vop/payins#banking-alias-categorization)). If the User owning the attached wallet has `UserCategory` of `OWNER` and the `KYCLevel` of `REGULAR`, then the `OwnerName` is set to the `FirstName` and `LastName` values for a [Natural User](/api-reference/users/natural-user-object-sca) or the `Name` value for a [Legal User](/api-reference/users/legal-user-object-sca). In this case, the `VirtualAccountPurpose` in the API response is `USER_OWNED`. If the User is not KYC verified and an `OWNER`, then the `OwnerName` is set to “MGP `PlatformTradingName`" in standard cases, or else “Mangopay” for Marketplace Payment Extension (MPE) workflows. In this case, the `VirtualAccountPurpose` in the API response is `COLLECTION`. **Caution:** Your platform must ensure that you use the `OwnerName` returned in the API response.
IBAN:
type: string
description: The IBAN (international bank account number) of the banking alias.
BIC:
type: string
description: The BIC (international identifier of the bank) for the banking alias.
CreditedUserId:
type: string
description: '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:
type: string
description: '**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:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
Active:
type: boolean
description: 'Whether or not the banking alias is active.
**Caution:** Setting this value to `false` is irreversible.'
Type:
type: string
description: '**Returned values:** `IBAN`, `GB`
The type of banking alias.
The `GB` value is only returned if the `Country` is `GB`.'
Id:
$ref: '#/components/schemas/Id'
WalletId:
type: string
description: The unique identifier of the wallet.
LocalAccountDetails:
$ref: '#/components/schemas/SortCodeAccountNumber'
title: CreateAnIBANBankingAliasResponse
Error:
type: object
properties:
Message:
type: string
description: Description of the error.
Type:
type: string
description: 'The category of the error.
'
Id:
type: string
description: Unique identifier of the error instance, useful when contacting Mangopay for support.
Date:
type: number
format: double
description: Unix timestamp (UTC) of the date and time the error was triggered.
errors:
type:
- object
- 'null'
additionalProperties:
type: string
description: 'Object containing one or more field-level errors.
'
description: 'The error body typically returned by the Mangopay API for any non-2xx HTTP status code.
'
title: Error
ViewABankingAliasForAWalletResponseArrayBankingAliasItems:
type: object
properties:
Object (Banking Alias):
$ref: '#/components/schemas/ViewABankingAliasForAWalletResponseArrayBankingAliasItemsObjectBankingAlias'
description: The Banking Alias object created by the platform.
title: ViewABankingAliasForAWalletResponseArrayBankingAliasItems
securitySchemes:
oauth2:
type: http
scheme: bearer
description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf 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."
x-provenance:
method: harvested
publisher: Mangopay
source: https://docs.mangopay.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)