POST
/
v2.01
/
{ClientId}
/
users
/
{UserId}
/
recipients
/
validate
{
    "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"
    }
}

// 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, LocalBankTransferThe 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, 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.
​
IndividualRecipient
object
required
The account holder if the RecipientType is Individual.Only one of IndividualRecipient or BusinessRecipient is required.

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

​
Responses

200

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

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, 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.
  • BIC_DOES_NOT_CORRESPOND_TO_ACCOUNT_COUNTRY – Bank identifier, IBAN, or account number does not match the Country value (for example, Country is GB but the IBAN starts with FR).
  • 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.
// No response body

{
    "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"
    }
}