Create a Recipient
Register a bank account for local or international payouts
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
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
, LocalBankTransfer
The payout method of the recipient:
InternationalBankTransfer
– A bank wire transfer sent via SWIFT, requiring theInternationalBankTransfer
property.LocalBankTransfer
– A bank wire transfer sent via local routes, requiring theLocalBankTransfer
property.
Possible values: Individual
, Business
The recipient type:
Individual
– An account held by a natural person, requiring theIndividualRecipient
property.Business
– An account held by a legal entity, requiring theBusinessRecipient
property.
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.
Format: Two-letter country code (ISO 3166-1 alpha-2 format)
The destination country of the payout method.
Possible values: PAYIN
, PAYOUT
Default value: PAYOUT
The scope of the recipient:
PAYOUT
– Usable for payouts and in pay-in use cases. APAYOUT
recipient can only be created by a user with theUserCategory
OWNER
and requires SCA. You need to use the returnedPendingUserAction.RedirectUrl
value, adding your encodedreturnUrl
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. APAYIN
recipient can be created by a user with theUserCategory
PAYER
orOWNER
, 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.
The account holder if the RecipientType
is Individual
.
Only one of IndividualRecipient
or BusinessRecipient
is required.
The account holder if the RecipientType
is Individual
.
Only one of IndividualRecipient
or BusinessRecipient
is required.
The account holder if the RecipientType
is Business
.
Only one of IndividualRecipient
or BusinessRecipient
is required.
The account details if PayoutMethodType
is InternationalBankTransfer
.
Only one of InternationalBankTransfer
or LocalBankTransfer
is required.
The InternationalBankTransfer
depends on the Currency
and Country
.
The account details if PayoutMethodType
is InternationalBankTransfer
.
Only one of InternationalBankTransfer
or LocalBankTransfer
is required.
The InternationalBankTransfer
depends on the Currency
and Country
.
The account details if PayoutMethodType
is LocalBankTransfer
, depending on the Currency
. One of:
Responses
201
201
Max length: 128 characters (see data formats for details)
The unique identifier of the object.
Possible values: PENDING
, CANCELED
, ACTIVE
, DEACTIVATED
The status of the recipient:
PENDING
– ForPAYOUT
scope recipients, the user must complete SCA before the recipient can becomeACTIVE
. ForPAYIN
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 anotherPendingUserAction.RedirectUrl
. TheCANCELED
status does not apply ifRecipientScope
isPAYIN
.ACTIVE
– Recipient creation was successful (including SCA ifRecipientScope
isPAYOUT
) 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
, LocalBankTransfer
The payout method of the recipient.
InternationalBankTransfer
– A bank wire transfer sent via SWIFT, requiring theInternationalBankTransfer
property.LocalBankTransfer
– A bank wire transfer sent via local routes, requiring theLocalBankTransfer
property.
Possible values: Individual
, Business
The recipient type:
Individual
– An account held by a natural person, requiring theIndividualRecipient
property.Business
– An account held by a legal entity, requiring theBusinessRecipient
property.
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.
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
, PAYOUT
Default value: PAYOUT
The scope of the recipient:
PAYOUT
– Usable for payouts and in pay-in use cases. APAYOUT
recipient can only be created by a user with theUserCategory
OWNER
and requires SCA. You need to use the returnedPendingUserAction.RedirectUrl
value, adding your encodedreturnUrl
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. APAYIN
recipient can be created by a user with theUserCategory
PAYER
orOWNER
, 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
.
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
, PAYOUT
Default value: PAYOUT
The scope of the recipient:
PAYOUT
– Usable for payouts and in pay-in use cases. APAYOUT
recipient can only be created by a user with theUserCategory
OWNER
and requires SCA. You need to use the returnedPendingUserAction.RedirectUrl
value, adding your encodedreturnUrl
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. APAYIN
recipient can be created by a user with theUserCategory
PAYER
orOWNER
, 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
.
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 account holder if the RecipientType
is Individual
.
The account details if PayoutMethodType
is InternationalBankTransfer
.
The account details if PayoutMethodType
is InternationalBankTransfer
.
Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned null
).
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
, orCurrency
.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 theCurrency
andCountry
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.
- If
INVALID_ACCOUNT_NUMBER_AND_SORT_CODE_COMBINATION
– GB sort code and account number combination is not valid.