Validate data for a Recipient

Check that the user’s Recipient data is valid before creation

POST /v2.01/{ClientId}/users/{UserId}/recipients/validate

REST - EUR, international, business, PAYOUT

{
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Country": "FR",
    "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"
    }
}

200

// No response body

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 – 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, 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.

Individual

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.

Business

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

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.

LocalBankTransfer

LocalBankTransfer · object · required

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

One of:

CAD

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

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

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

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

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

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

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

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

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

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

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

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

200

No response body – 200 HTTP code indicates the request is valid against the schema

400 - Parameter or data errors

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 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.

200

// No response body

REST - EUR, international, business, PAYOUT

{
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Country": "FR",
    "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"
    }
}