Create an IBAN Bank Account

POST

/v2.01/:ClientId/users/:UserId/bankaccounts/iban

POST

/v2.01/:ClientId/users/:UserId/bankaccounts/iban

$ curl -X POST https://api.sandbox.mangopay.com/v2.01/ClientId/users/UserId/bankaccounts/iban \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "body": {
>     "OwnerAddress": {
>       "AddressLine1": "Rue des plantes",
>       "AddressLine2": "The Oasis",
>       "City": "Paris",
>       "Region": "Ile de France",
>       "PostalCode": "75001",
>       "Country": "FR"
>     },
>     "IBAN": "FR7630004000031234567890143",
>     "BIC": "BNPAFRPP",
>     "OwnerName": "John Doe",
>     "Tag": "Created using the Mangopay API Postman collection"
>   }
> }'

1 {
2   "OwnerAddress": {
3     "AddressLine1": "Rue des plantes",
4     "AddressLine2": "The Oasis",
5     "City": "Paris",
6     "Region": "Ile de France",
7     "PostalCode": "75001",
8     "Country": "FR"
9   },
10   "IBAN": "FR7630004000031234567890143",
11   "BIC": "BNPAFRPP",
12   "UserId": "142036728",
13   "OwnerName": "John Doe",
14   "Type": "IBAN",
15   "Id": "150287803",
16   "Tag": "custom meta",
17   "CreationDate": 1661859994,
18   "Active": true
19 }

Caution - Payouts refused to Bank Accounts created after April 30, 2026

Bank Account objects created after April 30, 2026, will not be usable for payouts. External accounts must be registered using the Recipient endpoints and authenticated using SCA.

Payouts to Bank Accounts created after May 1, 2026, will fail with the ResultCode 121018. To resolve this, register the external account using POST Create a Recipient and retry the payout.

Note – Replaced by Recipients feature

The Bank Account object and endpoints have been replaced by the Recipients feature, which all platforms should integrate instead.

Legacy active Bank Accounts (Active is true) have been migrated to the new feature and their data is retrievable via the GET View a Recipient endpoint using the same BankAccountId. Read more about legacy bank account migration.

Note – Only for countries that use IBAN

Only use the IBAN type for accounts registered in countries that use IBAN and aren’t GB, US, or CA (for which you should use the dedicated type).

Create an IBAN Bank Account

<Warning icon="fa-regular fa-triangle-exclamation"> **Caution - Payouts refused to Bank Accounts created after April 30, 2026** Bank Account objects created after April 30, 2026, will not be usable for payouts. External accounts must be registered using the [Recipient endpoints](/api-reference/recipients/recipient-object) and authenticated using SCA. Payouts to Bank Accounts created after May 1, 2026, will fail with the `ResultCode` [121018](/errors/codes/121018). To resolve this, register the external account using [POST Create a Recipient](/api-reference/recipients/create-recipient) and retry the payout. </Warning> <Note icon="fa-regular fa-circle-info"> **Note – Replaced by Recipients feature** The Bank Account object and endpoints have been replaced by the Recipients feature, which all platforms should integrate instead. Legacy active Bank Accounts (`Active` is `true`) have been migrated to the new feature and their data is retrievable via the [GET View a Recipient](/api-reference/recipients/view-recipient) endpoint using the same `BankAccountId`. Read more about [legacy bank account migration](/guides/payouts#migration-of-legacy-bank-accounts). </Note> <Note icon="fa-regular fa-circle-info"> **Note – Only for countries that use IBAN** Only use the IBAN type for accounts registered in countries that use IBAN and aren’t GB, US, or CA (for which you should use the dedicated type). </Note> Create an IBAN Bank Account

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.

UserIdstringRequired

The unique identifier of the User (natural or legal) who owns the bank account.

Request

This endpoint expects an object.

OwnerAddressobjectRequired

The address of the platform operator’s headquarters. This parameter must be provided for the platform’s payouts to be processed.

IBANstringRequired

Max. length: 34 characters

The IBAN (international bank account number) of the bank account. It follows the CCDDBBAN format in which: - CC represents the country code (ISO 3166-1 alpha 2) - DD represents two check digits used by banking systems to avoid simple errors - BBAN stands for the Basic Bank Account Number which is up to 30 alphanumeric characters that are country-specific. Note: You will need a valid IBAN (i.e., existing in real life) when testing on a Sandbox account even if no actual payout will be processed.

OwnerNamestringRequired

Max. length: 255 characters

The full name of the owner of the bank account. (Format: FirstName LastName)

BICstringOptional

The BIC (international identifier of the bank) for IBAN or OTHER-type bank accounts.

The BIC can have one of the two following formats:

BIC8 – 8-character BIC (AAAABBCC)
BIC11 – 11-character BIC (AAAABBCCDDD)

In which:

AAAA represents the bank code: 4 characters defining the bank
BB represents the country code: 2 characters forming the country ISO code (ISO 3166 format)
CC represents the location code: 2 localization characters (alphabetical or numeric) to distinguish banks from the same country
DDD represents the branch code: 3 characters used to define the branch of the bank (sometimes replaced with XXX)

Note: On IBAN-type bank accounts, the full 11-character version (not using XXX) may be required for the BIC to be accepted as valid. Alternatively, this optional field can be omitted.

TagstringOptional

Max. length: 255 characters

Custom data that you can add to this object.

Response

Success

OwnerAddressobject

The postal address.

IBANstring

Max. length: 34 characters

BICstring

The BIC (international identifier of the bank) for IBAN or OTHER-type bank accounts.

The BIC can have one of the two following formats:

BIC8 – 8-character BIC (AAAABBCC)
BIC11 – 11-character BIC (AAAABBCCDDD)

In which:

AAAA represents the bank code: 4 characters defining the bank
BB represents the country code: 2 characters forming the country ISO code (ISO 3166 format)
CC represents the location code: 2 localization characters (alphabetical or numeric) to distinguish banks from the same country
DDD represents the branch code: 3 characters used to define the branch of the bank (sometimes replaced with XXX)

UserIdstring

The unique identifier of the user.

OwnerNamestring

Max. length: 255 characters

The full name of the owner of the bank account. (Format: FirstName LastName)

Typestring

Returned values: IBAN, US, CA, GB, OTHER

The type of the bank account, indicating the country where the real-life account is registered The values are:

IBAN – For accounts registered in countries that use IBAN
US – For accounts registered in the United States
CA – For accounts registered in Canada
GB – For accounts registered in the United Kingdom
OTHER – For accounts registered in countries that do not use IBAN (and are not US, CA, GB)

Idstring

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

The unique identifier of the object.

Tagstring

Max. length: 255 characters

Custom data that you can add to this object.

CreationDateinteger

Unix timestamp (UTC) of the date and time the object was created.

Activeboolean

Whether or not the Bank Account is active. Mangopay automatically sets this parameter to false if the bank account is closed or does not exist anymore.

Errors

400

Bad Request Error