Skip to main content
POST
/
v2.01
/
{ClientId}
/
users
/
{UserId}
/
bankaccounts
/
iban
{
    "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"
}  
{
    "OwnerAddress":{
        "AddressLine1":"Rue des plantes",
        "AddressLine2":"The Oasis",
        "City":"Paris",
        "Region":"Ile de France",
        "PostalCode":"75001",
        "Country":"FR"
    },
    "IBAN":"FR7630004000031234567890143",
    "BIC":"BNPAFRPP",
    "UserId":"142036728",
    "OwnerName":"John Doe",
    "Type":"IBAN",
    "Id":"150287803",
    "Tag":"custom meta",
    "CreationDate":1661859994,
    "Active":true
}  
Caution – Replaced by Recipients featureThe 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 IBANOnly 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). 

Path parameters

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

Body parameters

OwnerAddress
object
required
Information about the address of residence of the bank account owner.
IBAN
string
required
Max. length: 34 charactersThe 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.
BIC
string
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.
OwnerName
string
required
Max. length: 255 charactersThe full name of the owner of the bank account. (Format: FirstName LastName)
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.
For bank accounts, you can use this parameter to identify the bank account by currency or usage (personal or professional for instance).

Responses

OwnerAddress
object
Information about the address of residence of the bank account owner.
IBAN
string
Max. length: 34 charactersThe 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.
BIC
string
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)
UserId
string
The unique identifier of the user.
OwnerName
string
Max. length: 255 charactersThe full name of the owner of the bank account. (Format: FirstName LastName)
Type
string
Returned values: IBAN, US, CA, GB, OTHERThe 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)
Id
string
Max length: 128 characters (see data formats for details)The unique identifier of the object.
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.
For bank accounts, you can use this parameter to identify the bank account by currency or usage (personal or professional for instance).
CreationDate
Unix timestamp
The date and time at which the object was created.
Active
boolean
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.
{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "c35b1e0b-1a21-42e4-a80f-440ad9de3c57#1662449222",
    "Date": 1662449223.0,
    "errors": {
        "BIC": "The field BIC must match the regular expression '^[a-zA-Z]{6}\\w{2}(\\w{3})?$'."
    }
}
{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "709e198c-c72a-4589-8055-b210c3360893#1745589614",
    "Date": 1745589615,
    "errors": {
        "BIC": "The value is not a valid BIC"
    }
}
{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "692b34b2-86a5-4859-a515-f8838292a56e#1662449297",
    "Date": 1662449298.0,
    "errors": {
        "IBAN": "The value is not a valid IBAN"
    }
}  
{
    "OwnerAddress":{
        "AddressLine1":"Rue des plantes",
        "AddressLine2":"The Oasis",
        "City":"Paris",
        "Region":"Ile de France",
        "PostalCode":"75001",
        "Country":"FR"
    },
    "IBAN":"FR7630004000031234567890143",
    "BIC":"BNPAFRPP",
    "UserId":"142036728",
    "OwnerName":"John Doe",
    "Type":"IBAN",
    "Id":"150287803",
    "Tag":"custom meta",
    "CreationDate":1661859994,
    "Active":true
}  
{
    "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"
}  
I