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 (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.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
The unique identifier of the user.
Body parameters
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.Possible values:
InternationalBankTransfer, LocalBankTransferThe payout method of the recipient:InternationalBankTransfer– A bank wire transfer sent via SWIFT, requiring theInternationalBankTransferproperty.LocalBankTransfer– A bank wire transfer sent via local routes, requiring theLocalBankTransferproperty.
Possible values:
Individual, BusinessThe recipient type:Individual– An account held by a natural person, requiring theIndividualRecipientproperty.Business– An account held by a legal entity, requiring theBusinessRecipientproperty.
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.Format: Two-letter country code (ISO 3166-1 alpha-2 format)The destination country of the payout method.
Possible values:
PAYIN, PAYOUTDefault value: PAYOUTThe scope of the recipient:PAYOUT– Usable for payouts and in pay-in use cases. APAYOUTrecipient can only be created by a user with theUserCategoryOWNERand requires SCA. You need to use the returnedPendingUserAction.RedirectUrlvalue, adding your encodedreturnUrlas 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. APAYINrecipient can be created by a user with theUserCategoryPAYERorOWNER, and does not require SCA.
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
The account holder if the
RecipientType is Individual.Only one of IndividualRecipient or BusinessRecipient is required.- InternationalBankTransfer
- LocalBankTransfer
The account details if
PayoutMethodType is InternationalBankTransfer.Only one of InternationalBankTransfer or LocalBankTransfer is required.The InternationalBankTransfer depends on the Currency and Country.Responses
201
201
Max length: 128 characters (see data formats for details)The unique identifier of the object.
Possible values:
PENDING, CANCELED, ACTIVE, DEACTIVATEDThe status of the recipient:PENDING– ForPAYOUTscope recipients, the user must complete SCA before the recipient can becomeACTIVE. ForPAYINscope 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 anotherPendingUserAction.RedirectUrl. TheCANCELEDstatus does not apply ifRecipientScopeisPAYIN.ACTIVE– Recipient creation was successful (including SCA ifRecipientScopeisPAYOUT) and the recipient is ready to be used for payouts .DEACTIVATED– The recipient has been permanently deactivated and can no longer be used.
The date and time at which the object was created.
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.Possible values:
InternationalBankTransfer, LocalBankTransferThe payout method of the recipient.InternationalBankTransfer– A bank wire transfer sent via SWIFT, requiring theInternationalBankTransferproperty.LocalBankTransfer– A bank wire transfer sent via local routes, requiring theLocalBankTransferproperty.
Possible values:
Individual, BusinessThe recipient type:Individual– An account held by a natural person, requiring theIndividualRecipientproperty.Business– An account held by a legal entity, requiring theBusinessRecipientproperty.
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.Format: Two-letter country code (ISO 3166-1 alpha-2 format)The destination country of the payout method.
The unique identifier of the user.
Possible values:
PAYIN, PAYOUTDefault value: PAYOUTThe scope of the recipient:PAYOUT– Usable for payouts and in pay-in use cases. APAYOUTrecipient can only be created by a user with theUserCategoryOWNERand requires SCA. You need to use the returnedPendingUserAction.RedirectUrlvalue, adding your encodedreturnUrlas 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. APAYINrecipient can be created by a user with theUserCategoryPAYERorOWNER, and does not require SCA.
PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.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.The unique identifier of the user.
Possible values:
PAYIN, PAYOUTDefault value: PAYOUTThe scope of the recipient:PAYOUT– Usable for payouts and in pay-in use cases. APAYOUTrecipient can only be created by a user with theUserCategoryOWNERand requires SCA. You need to use the returnedPendingUserAction.RedirectUrlvalue, adding your encodedreturnUrlas 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. APAYINrecipient can be created by a user with theUserCategoryPAYERorOWNER, and does not require SCA.
PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.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
The account holder if the
RecipientType is Individual.- InternationalBankTransfer
- LocalBankTransfer
The account details if
PayoutMethodType is InternationalBankTransfer.Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned
null).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.400
400
Example 400 error: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 validPayoutMethodType,RecipientType,CurrencyorCountry.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 theCurrencyandCountrycombination.CLIENT_NOT_FOUND–ClientIdmaking the request does not exist.USER_NOT_FOUND–UserIdfor 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 theCountryvalue (for example,CountryisGBbut the IBAN starts withFR).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.
- If
INVALID_ACCOUNT_NUMBER_AND_SORT_CODE_COMBINATION– GB sort code and account number combination is not valid.