Create a Recipient - Mangopay docs

{
    "ScaContext": "USER_PRESENT",
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "Tag": "Created using the Mangopay API Postman collection",
    "RecipientScope": "PAYOUT",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {        
            "IBAN": "DE75512108001245126199"
        }
    }
}

{
    "ScaContext": "USER_PRESENT",
    "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
    "Status": "PENDING",
    "CreationDate": 1759228005,
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {
            "IBAN": "DE75512108001245126199",
            "BIC": "SOGEDEFFXXX"
        }
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
    },
    "RecipientVerificationOfPayee": {
        "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
        "RecipientVerificationCheck": "MATCH",
        "RecipientVerificationMessage": "Account name fully matches account identifier."
    }
}

POST

v2.01

{ClientId}

users

{UserId}

recipients

{
    "ScaContext": "USER_PRESENT",
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "Tag": "Created using the Mangopay API Postman collection",
    "RecipientScope": "PAYOUT",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {        
            "IBAN": "DE75512108001245126199"
        }
    }
}

{
    "ScaContext": "USER_PRESENT",
    "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
    "Status": "PENDING",
    "CreationDate": 1759228005,
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {
            "IBAN": "DE75512108001245126199",
            "BIC": "SOGEDEFFXXX"
        }
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
    },
    "RecipientVerificationOfPayee": {
        "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
        "RecipientVerificationCheck": "MATCH",
        "RecipientVerificationMessage": "Account name fully matches account identifier."
    }
}

Caution – Fetch schema and validate data before creationBefore 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 endpointRegistering a bank account as a Recipient always requires the user to authenticate using SCA on a Mangopay-hosted webpage, unless your platform is using a proxy and user consent.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.If SCA is not successfully completed, the Recipient Status becomes CANCELED and you need to create a new Recipient to try again.In Sandbox, you can bypass SCA by including the word accept in the Email value of the Natural User or the LegalRepresentative.Email value of the Legal User – for example accept@example.com or john.doe+accept@example.com.

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. Verification of Payee (VOP) impacts SEPA local schemes, which means Recipients with Currency value EUR and PayoutMethod value LocalBankTransfer. Read more →

Path parameters

UserId

string

required

The unique identifier of the user.

Body parameters

ScaContext

string

Possible values: USER_PRESENT, USER_NOT_PRESENTDefault value: USER_PRESENTThe SCA context of the request, which is required if the user’s UserCategory is OWNER:

USER_PRESENT – The user is taking the SCA-triggering action of registering an external account as a Recipient. The platform must redirect the user using the PendingUserAction.RedirectUrl returned so that the user can complete the SCA session.
USER_NOT_PRESENT – The platform is taking the action under proxy from the user and the user has previously given consent to Mangopay (via the SCA hosted experience) to allow the action. If the user has not given (or has revoked) their consent, then USER_NOT_PRESENT returns a 403 error.

Read more about managing proxy and user consent →Note: On the Recipient endpoint, ScaContext is not returned in the API response as it does not form part of the Recipient data – it’s only related to the action being performed to register the account.

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, LocalBankTransferThe payout method of the recipient:

InternationalBankTransfer – The account can receive non-local currencies via SWIFT or else uses local rails for local currencies by default.
LocalBankTransfer – The account can only receive the corresponding local Currency for the Country (e.g. EUR to a SEPA country, GBP to a UK account, PLN to a Polish IBAN, etc.)

RecipientType

string

required

Possible values: Individual, BusinessThe 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, ZARThe 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, PAYOUTDefault value: PAYOUTThe 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.

Individual
Business

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
LocalBankTransfer

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 CountryThe 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 CountryThe 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–50The 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

string

Max length: 128 characters (see data formats for details)The unique identifier of the object.

Status

string

Possible values: PENDING, CANCELED, ACTIVE, DEACTIVATEDThe status of the recipient:

PENDING – For PAYOUT scope recipients, the user must complete SCA before the recipient can become ACTIVE. For PAYIN scope recipients, the recipient creation is in progress.
CANCELED – SCA was not successfully completed and the recipient creation request was canceled. To retry, create another recipient to retrieve another PendingUserAction.RedirectUrl. The CANCELED status does not apply if RecipientScope is PAYIN.
ACTIVE – Recipient creation was successful (including SCA if RecipientScope is PAYOUT) and the recipient is ready to be used for payouts .
DEACTIVATED – The recipient has been permanently deactivated and can no longer be used.

CreationDate

Unix timestamp

The date and time at which the object was created.

DisplayName

string

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

Possible values: InternationalBankTransfer, LocalBankTransferThe payout method of the recipient:

LocalBankTransfer – The account can only receive the corresponding local Currency for the Country via the domestic payment rail (e.g. EUR via a SEPA local scheme to a SEPA country, GBP via FPS to a GB account, USD via ACH to a US account, etc). Payouts in non-local currencies return an error.
InternationalBankTransfer – The account can receive both non-local currencies via SWIFT and also local currency via domestic rails.

RecipientType

string

Possible values: Individual, BusinessThe 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

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The destination country of the payout method.

UserId

string

The unique identifier of the user.

RecipientScope

string

Possible values: PAYIN, PAYOUTDefault value: PAYOUTThe 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.

Both PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.

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.

UserId

string

The unique identifier of the user.

RecipientScope

string

Possible values: PAYIN, PAYOUTDefault value: PAYOUTThe 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.

Both PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.

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.

Individual
Business

IndividualRecipient

object

The account holder if the RecipientType is Individual.

Show properties

FirstName

string

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)The first name of the individual account holder.

LastName

string

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)The last name of the individual account holder.

Address

object

Information about the address.

Show properties

AddressLine1

string

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. Parameter only returned if sent.

City

string

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. Parameter only returned if sent.

PostalCode

string

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

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The country of the address.

BusinessRecipient

object

The account holder if the RecipientType is Business.

Show properties

BusinessName

string

Length: 1–255; cannot contain: (),.:/ (Pattern: ^(?!.*[(),.:/]).{1,255}$)The name of the business account holder.

Address

object

Information about the address.

Show properties

AddressLine1

string

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. Parameter only returned if sent.

City

string

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. Parameter only returned if sent.

PostalCode

string

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

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The country of the address.

InternationalBankTransfer
LocalBankTransfer

InternationalBankTransfer

object

The account details if PayoutMethodType is InternationalBankTransfer.

Show properties

AccountNumber

string

The account number of the account.

BIC

string

The BIC of the account. For IBAN countries, the returned BIC is generated from the IBAN.

LocalBankTransfer

object

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

CAD

object

Hide properties

AccountNumber

string

Format: 7–35 digits (pattern: ^\\d{7,35}$)The account number of the Canadian account.

InstitutionNumber

string

Format: 3 digits (pattern: ^\\d{3}$)The institution number of the Canadian account.

BranchCode

string

Format: 5 digits (pattern: ^\\d{5}$)The branch code of the Canadian account.

BankName

string

Length: 1–50The bank name of the Canadian account.

CHF

object

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

AccountNumber

string

Format: 8 digits (pattern: ^\\d{8}$)The account number of the UK account.

SortCode

string

Format: 6 digits (pattern: ^\\d{6}$)The sort code of the UK account.

HUF

object

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

IBAN

string

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

Hide properties

AccountNumber

string

Format: 8–12 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8,12}$)The account number of the US account.

ABA

string

Format: 9 digits (pattern: ^\\d{9}$)The ABA routing number of the US account.

FFC

string

PendingUserAction

object

Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned null).

Hide properties

RedirectUrl

string

The URL to which to redirect the user to perform strong customer authentication (SCA) via a Mangopay-hosted webpage. This value is a variable and should not be hardcoded.The SCA session link expires 10 minutes after it’s generated.Caution: Before redirecting the user on this URL, you must add the query parameter ReturnUrl with the percent-encoded URL to which you want the SCA session to return the user after authentication (whether successful or not).For more details, see How to redirect a user for an SCA session.

RecipientVerificationOfPayee

object

Information about the Verification of Payee (VOP) check performed on the Recipient. Because VOP only applies to SEPA local schemes, this object is returned null if the Recipient’s Currency is not EUR or its PayoutMethod is not LocalBankTransfer.

Show child attributes

RecipientVerificationId

string

The unique identifier of the VOP check. This value may be null if the check could not be performed.

RecipientVerificationCheck

string

Possible values: MATCH, CLOSE_MATCH, NO_MATCH, MATCH_NOT_POSSIBLEThe result of the VOP check:

MATCH – The account is valid and the account name matches the IBAN.
CLOSE_MATCH – The account is valid but the name doesn’t match exactly.
NO_MATCH – This account likely belongs to a different owner.
MATCH_NOT_POSSIBLE – The check could not be completed.

RecipientVerificationMessage

string

The explanation of the RecipientVerificationCheck:

If MATCH, then Account name fully matches account identifier.
If CLOSE_MATCH, then Account name partially matches account identifier. Name returned by check: {Name}. Payment made to this account may not reach its intended counterparty.
If NO_MATCH, then Account name does not matches account identifier. Payment made to this account may not reach its intended counterparty.
If MATCH_NOT_POSSIBLE, then Account name does not matches account identifier. Payment made to this account may not reach its intended counterparty.

RecipientVerificationPayeeSuggestedName

string

The name returned by the check in case of a CLOSE_MATCH result, which can be used to re-register the Recipient. This property is not returned on the check performed on a Payout request, even if the result is CLOSE_MATCH.

400 - Parameter or data errors

Example 400 error:

{
    "Id": "1a8bff3c-37a4-4a1a-9219-d00a5fd19865",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1779197001,
    "Errors": {
        "IndividualRecipient.Address.PostalCode": "LENGTH_MORE_THAN_MAX",
        "LocalBankTransfer.GBP.AccountNumber": "INVALID_FORMAT. Regex validation: ^\\d{8}$",
        "LocalBankTransfer.GBP.SortCode": "INVALID_FORMAT. Regex validation: ^\\d{6}$"
    }
}

The following Errors values may be returned for a given parameter:

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, Currency or Country.
UNSUPPORTED_COUNTRY – Country not allowed (see country restrictions article for details).
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.
IBAN_DOES_NOT_CORRESPOND_TO_ACCOUNT_COUNTRY – IBAN or account number does not match the Country value (for example, Country is GB but the IBAN starts with FR).
BIC_DOES_NOT_CORRESPOND_TO_ACCOUNT_COUNTRY – Bank identifier does not match the Country value (for example, Country is JP but the BIC indicates US).
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.

400 - LocalBankTransfer EUR not available because bank not part of SCT

{
    "Id": "ac382a41-5c6f-47fb-8ef4-5fcf43ae1c50",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1772979930,
    "Errors": {
        "Reachability": "LOCAL_BANK_TRANSFER_NOT_AVAILABLE_AS_BANK_ACCOUNT_NOT_SEPA_REACHABLE"
    }
}

This error may be returned for a LocalBankTransfer request in EUR if the IBAN is not reachable on SEPA Credit Transfer (SCT), particularly relevant for accounts registered in countries that operate other local schemes: CH, CZ, DK, GB, HU, NO, PL, RO, SE.

400 - User is PAYER but RecipientScope set to PAYOUT

{
    "Id": "6e5f4718-7e68-4348-9967-84645261007f",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1762350143,
    "Errors": {
        "SCA": "2815488948686553431"
    }
}

This error occurs when RecipientScope is set to PAYOUT but the user’s UserCategory is PAYER. A user must be an OWNER to register a Recipient that can be used for payouts.

400 - Legal User is missing LegalRepresentative.Email

{
    "Id": "b8c130e9-1e18-4c67-80e6-a968a015608c",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1762356390,
    "Errors": {
        "SCA": "KAR_0042"
    }
}

This error typically means that a Legal User is missing the LegalRepresentative.Email, which is required to perform SCA. Prior to the introduction of SCA, it was possible to create a Legal User without the legal representative’s email.

401 - Consent not given for proxy when USER_NOT_PRESENT sent

{
    "Id": "729e9ad7-d4d2-453c-8e7a-6863117a3945",
    "Message": "You are not authorized to perform this action. The user has not provided consent to the requested proxy.",
    "Type": "sca_proxy_consent_required",
    "Date": 1763384886,
    "Errors": null
}

{
    "ScaContext": "USER_PRESENT",
    "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
    "Status": "PENDING",
    "CreationDate": 1759228005,
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {
            "IBAN": "DE75512108001245126199",
            "BIC": "SOGEDEFFXXX"
        }
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
    },
    "RecipientVerificationOfPayee": {
        "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
        "RecipientVerificationCheck": "MATCH",
        "RecipientVerificationMessage": "Account name fully matches account identifier."
    }
}

{
    "ScaContext": "USER_PRESENT",
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "Tag": "Created using the Mangopay API Postman collection",
    "RecipientScope": "PAYOUT",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {        
            "IBAN": "DE75512108001245126199"
        }
    }
}

Validate data for a Recipient Deactivate a Recipient

​Path parameters

​Body parameters

​Responses

Path parameters

Body parameters

Responses