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, 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 (when RecipientScope is PAYOUT) 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 PayoutMethodType value LocalBankTransfer. Read more →
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
If your platform is using a proxy to take SCA-triggering action on behalf of users, you also need to integrate mTLS authentication and use the api-mtls base URL.
Path parameters
Request
Request body for creating a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Individual.
Request body for creating a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Business.
Request body for creating a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Individual.
Request body for creating a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Business.
Response
Response body for a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Individual.
Response body for a Recipient where PayoutMethodType is
InternationalBankTransfer and RecipientType is Business.
Response body for a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Individual.
Response body for a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Business.