Create a Recipient

POST

v2.01

{ClientId}

users

{UserId}

recipients

{
    "DisplayName": "Alex Smith EUR IBAN account",
    "Tag": "Created using the Mangopay API Postman collection",
    "PayoutMethodType": "InternationalBankTransfer",
    "Currency": "EUR",
    "Country": "FR",
    "RecipientType": "Business",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143"
    }
}

{
    "Id": "rec_01JRADYFJYPFM10XPQ8VFWW947",
    "Status": "PENDING",
    "CreationDate": 1744106896,
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Country": "FR",
    "UserId": "user_m_01JRADX7YD0060N5VAA0XPMM54",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143",
        "BIC": "BNPAFRPPXXX"
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_019614df3f3b7b08847111a76d9f9924"
    }
}

Caution – Fetch schema and validate data before creation

Before using this endpoint to register a Recipient for a user, for the given currency, payout method, and recipient type combination, always:

Fetch the schema dynamically using GET View the schema for a Recipient
Check that the user’s data is valid using POST Validate data for a Recipient

Note – SCA triggered by this endpoint

Registering a bank account as a Recipient always requires the user to authenticate using SCA on a Mangopay-hosted webpage (read more about SCA on recipients).

To let the user complete the SCA session, your platform needs to retrieve the returned PendingUserAction.RedirectUrl, add an encoded returnUrl query parameter, and redirect the user. Read more about how to redirect them in the SCA session guide.

Recipient creation is asynchronous, meaning that this endpoint returns the Status as PENDING regardless of whether SCA is required (because RecipientScope is OWNER) or not. In all cases, your integration should rely on the RECIPIENT_ACTIVE webhook to know when the recipient is ACTIVE.

Path parameters

UserId

string

required

The unique identifier of the user.

Body parameters

DisplayName

string

required

Length: 1–50; cannot contain: &,'/ (pattern:^(?!.*[&,'/]).{1,50}$)

A user-friendly name to identify the account. This value cannot be changed once the recipient is created.

PayoutMethodType

string

required

Possible values: InternationalBankTransfer, LocalBankTransfer

The payout method of the recipient:

InternationalBankTransfer – A bank wire transfer sent via SWIFT, requiring the InternationalBankTransfer property.
LocalBankTransfer – A bank wire transfer sent via local routes, requiring the LocalBankTransfer property.

RecipientType

string

required

Possible values: Individual, Business

The recipient type:

Individual – An account held by a natural person, requiring the IndividualRecipient property.
Business – An account held by a legal entity, requiring the BusinessRecipient property.

Currency

string

required

Possible values: AED, AUD, CAD, CHF, CNH, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, TRY, USD, ZAR

The currency of the recipient.

Country

string

required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The destination country of the payout method.

RecipientScope

string

Possible values: PAYIN, PAYOUT

Default value: PAYOUT

The scope of the recipient:

PAYOUT – Usable for payouts and in pay-in use cases. A PAYOUT recipient can only be created by a user with the UserCategory OWNER and requires SCA. You need to use the returned PendingUserAction.RedirectUrl value, adding your encoded returnUrl as a query parameter, to redirect the user to the hosted SCA session so they can complete the necessary steps.
PAYIN - Not usable for payouts but only usable for pay-in use cases, such as direct debit and refunds using payouts. A PAYIN recipient can be created by a user with the UserCategory PAYER or OWNER, and does not require SCA.

Tag

string

Max. length: 255 (pattern: ^.{0,255}$)

Custom data that you can add to this object. This value cannot be changed once the recipient is created.

IndividualRecipient

object

required

The account holder if the RecipientType is Individual.

Only one of IndividualRecipient or BusinessRecipient is required.

Show properties

FirstName

string

required

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)

The first name of the individual account holder.

LastName

string

required

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)

The last name of the individual account holder.

Address

object

required

Information about the address.

Show properties

AddressLine1

string

required

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The first line of the address.

AddressLine2

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The second line of the address.

City

string

required

Length: 1-80; cannot contain: &,.:_' (pattern: ^(?!.*[&,.:_']).{1,80}$)

The city of the address.

Region

string

Length: 1–10; cannot contain: &,.:_'-/ (pattern: ^(?!.*[&,.:_'-/]).{1,50}$)

The region of the address.

PostalCode

string

required

Length: 1–10; cannot contain: ()&,.:_'/ (pattern: ^(?!.*[()&,.:_'/]).{1,10}$)

The postal code of the address.

Country

string

required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

IndividualRecipient

object

required

The account holder if the RecipientType is Individual.

Only one of IndividualRecipient or BusinessRecipient is required.

Show properties

FirstName

string

required

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)

The first name of the individual account holder.

LastName

string

required

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)

The last name of the individual account holder.

Address

object

required

Information about the address.

Show properties

AddressLine1

string

required

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The first line of the address.

AddressLine2

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The second line of the address.

City

string

required

Length: 1-80; cannot contain: &,.:_' (pattern: ^(?!.*[&,.:_']).{1,80}$)

The city of the address.

Region

string

Length: 1–10; cannot contain: &,.:_'-/ (pattern: ^(?!.*[&,.:_'-/]).{1,50}$)

The region of the address.

PostalCode

string

required

Length: 1–10; cannot contain: ()&,.:_'/ (pattern: ^(?!.*[()&,.:_'/]).{1,10}$)

The postal code of the address.

Country

string

required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

BusinessRecipient

object

required

The account holder if the RecipientType is Business.

Only one of IndividualRecipient or BusinessRecipient is required.

Show properties

BusinessName

string

required

Length: 1–255; cannot contain: (),.:/ (Pattern: ^(?!.*[(),.:/]).{1,255}$)

The name of the business account holder.

Address

object

required

Information about the address.

Show properties

AddressLine1

string

required

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The first line of the address.

AddressLine2

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)

The second line of the address.

City

string

required

Length: 1-80; cannot contain: &,.:_' (pattern: ^(?!.*[&,.:_']).{1,80}$)

The city of the address.

Region

string

Length: 1–10; cannot contain: &,.:_'-/ (pattern: ^(?!.*[&,.:_'-/]).{1,50}$)

The region of the address.

PostalCode

string

required

Length: 1–10; cannot contain: ()&,.:_'/ (pattern: ^(?!.*[()&,.:_'/]).{1,10}$)

The postal code of the address.

Country

string

required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

InternationalBankTransfer

object

required

The account details if PayoutMethodType is InternationalBankTransfer.

Only one of InternationalBankTransfer or LocalBankTransfer is required.

The InternationalBankTransfer depends on the Currency and Country.

Hide properties

AccountNumber

string

required

Format: The format returned by the schema endpoint depending on the Currency and Country

The account number of the account. For IBAN countries, the AccountNumber format is the local IBAN one. For other countries, the format depends on the Country and should be retrieved from the GET View the schema for a Recipient endpoint.

BIC

string

Format: The format returned by the schema endpoint depending on the Currency and Country

The BIC of the account.

For countries that don’t use IBAN, the BIC is required. For countries that use IBAN, this field is ignored because the BIC generated automatically from the IBAN and returned in the response.

InternationalBankTransfer

object

required

The account details if PayoutMethodType is InternationalBankTransfer.

Only one of InternationalBankTransfer or LocalBankTransfer is required.

The InternationalBankTransfer depends on the Currency and Country.

Hide properties

AccountNumber

string

required

Format: The format returned by the schema endpoint depending on the Currency and Country

BIC

string

Format: The format returned by the schema endpoint depending on the Currency and Country

The BIC of the account.

For countries that don’t use IBAN, the BIC is required. For countries that use IBAN, this field is ignored because the BIC generated automatically from the IBAN and returned in the response.

LocalBankTransfer

object

required

The account details if PayoutMethodType is LocalBankTransfer, depending on the Currency. One of:

CAD

object

required

Hide properties

AccountNumber

string

required

Format: 7–35 digits (pattern: ^\\d{7,35}$)

The account number of the Canadian account.

InstitutionNumber

string

required

Format: 3 digits (pattern: ^\\d{3}$)

The institution number of the Canadian account.

BranchCode

string

required

Format: 5 digits (pattern: ^\\d{5}$)

The branch code of the Canadian account.

BankName

string

required

Length: 1–50

The bank name of the Canadian account.

CAD

object

required

Hide properties

AccountNumber

string

required

Format: 7–35 digits (pattern: ^\\d{7,35}$)

The account number of the Canadian account.

InstitutionNumber

string

required

Format: 3 digits (pattern: ^\\d{3}$)

The institution number of the Canadian account.

BranchCode

string

required

Format: 5 digits (pattern: ^\\d{5}$)

The branch code of the Canadian account.

BankName

string

required

Length: 1–50

The bank name of the Canadian account.

CHF

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

CZK

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

DKK

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

EUR

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

GBP

object

required

Hide properties

AccountNumber

string

required

Format: 8 digits (pattern: ^\\d{8}$)

The account number of the UK account.

SortCode

string

required

Format: 6 digits (pattern: ^\\d{6}$)

The sort code of the UK account.

HUF

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

NOK

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

PLN

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

RON

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

SEK

object

required

Hide properties

IBAN

string

required

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

USD

object

required

Hide properties

AccountNumber

string

required

Format: 8–12 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8,12}$)

The account number of the US account.

ABA

string

required

Format: 9 digits (pattern: ^\\d{9}$)

The ABA routing number of the US account.

FFC

string

Format: 8-12 digits then FFC then a space then a sting of characters up to 140 total length (pattern: ^(?=.{0,140}$)[0-9]{8,12}/FFC [0-9a-zA-Z/\\-?:().,'+ ]+$)

FFC transfer information for the US account.

Responses

201

400

Example 400 error:

{
    "Id": "a1f3db88-9df5-49a8-b73c-d578ffff6e89",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1739182373,
    "Errors": {
        "IndividualRecipient.Address.Region": "INVALID_FORMAT",
        "LocalBankTransfer.GBP.AccountNumber": "LENGTH_LESS_THAN_MIN"
    }
}

The following error values may be returned:

REQUIRED – Value is required but not present in the request.
LENGTH_MORE_THAN_MAX – String length is greater than required length.
LENGTH_LESS_THAN_MIN – String length is less than required length.
INVALID_FORMAT – Value doe not match expected pattern.
NOT_IN_ALLOWED_VALUES – Value is not a valid PayoutMethodType, RecipientType, or Currency.
UNSUPPORTED_CURRENCY – Currency is a valid ISO 4217 format but not yet supported for Recipients.
UNSUPPORTED_PAYOUT_METHOD_FOR_CURRENCY – Payout method is not supported for the Currency and Country combination.
CLIENT_NOT_FOUND – ClientId making the request does not exist.
USER_NOT_FOUND – UserId for which the request is made does not exist.
INVALID_SORT_CODE – Sort code for this account is not valid.
INVALID_ACCOUNT_NUMBER – Account number is not valid.
INVALID_IBAN – IBAN is not valid.
INVALID_BIC – BIC is not valid.
UNSUPPORTED_IBAN – IBAN is valid but not supported:
- If LocalBankTransfer, the IBAN country is not part of SEPA and the local currency is not EUR.
- If InternationalBankTransfer, the IBAN country is not GB or is not part of SEPA and local currency is not EUR.
INVALID_ACCOUNT_NUMBER_AND_SORT_CODE_COMBINATION – GB sort code and account number combination is not valid.

{
    "Id": "rec_01JRADYFJYPFM10XPQ8VFWW947",
    "Status": "PENDING",
    "CreationDate": 1744106896,
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Country": "FR",
    "UserId": "user_m_01JRADX7YD0060N5VAA0XPMM54",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143",
        "BIC": "BNPAFRPPXXX"
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_019614df3f3b7b08847111a76d9f9924"
    }
}

{
    "DisplayName": "Alex Smith EUR IBAN account",
    "Tag": "Created using the Mangopay API Postman collection",
    "PayoutMethodType": "InternationalBankTransfer",
    "Currency": "EUR",
    "Country": "FR",
    "RecipientType": "Business",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143"
    }
}

Validate data for a Recipient Deactivate a Recipient

{
    "DisplayName": "Alex Smith EUR IBAN account",
    "Tag": "Created using the Mangopay API Postman collection",
    "PayoutMethodType": "InternationalBankTransfer",
    "Currency": "EUR",
    "Country": "FR",
    "RecipientType": "Business",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143"
    }
}

{
    "Id": "rec_01JRADYFJYPFM10XPQ8VFWW947",
    "Status": "PENDING",
    "CreationDate": 1744106896,
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Country": "FR",
    "UserId": "user_m_01JRADX7YD0060N5VAA0XPMM54",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "AccountNumber": "FR7630004000031234567890143",
        "BIC": "BNPAFRPPXXX"
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_019614df3f3b7b08847111a76d9f9924"
    }
}

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Helpers

Platform account

Path parameters

Body parameters

Responses

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Helpers

Platform account

​Path parameters

​Body parameters

​Responses

Path parameters

Body parameters

Responses