Create a Recipient

POST

/v2.01/:ClientId/users/:UserId/recipients

POST

/v2.01/:ClientId/users/:UserId/recipients

$ curl -X POST https://api.sandbox.mangopay.com/v2.01/ClientId/users/UserId/recipients \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "body": {
>     "ScaContext": "USER_PRESENT",
>     "DisplayName": "John Doe EUR DE account",
>     "PayoutMethodType": "LocalBankTransfer",
>     "RecipientType": "Individual",
>     "Currency": "EUR",
>     "Country": "DE",
>     "Tag": "Created using the Mangopay API Postman collection",
>     "RecipientScope": "PAYOUT",
>     "IndividualRecipient": {
>       "FirstName": "John",
>       "LastName": "Doe",
>       "Address": {
>         "AddressLine1": "Oranienburger Str. 87",
>         "City": "Berlin",
>         "PostalCode": "10178",
>         "Country": "DE"
>       }
>     },
>     "LocalBankTransfer": {
>       "EUR": {
>         "IBAN": "DE75512108001245126199"
>       }
>     }
>   }
> }'

1 {
2   "ScaContext": "USER_PRESENT",
3   "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
4   "Status": "PENDING",
5   "CreationDate": 1759228005,
6   "DisplayName": "John Doe EUR DE account",
7   "PayoutMethodType": "LocalBankTransfer",
8   "RecipientType": "Individual",
9   "Currency": "EUR",
10   "Country": "DE",
11   "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
12   "RecipientScope": "PAYOUT",
13   "Tag": "Created using the Mangopay API Postman collection",
14   "IndividualRecipient": {
15     "FirstName": "John",
16     "LastName": "Doe",
17     "Address": {
18       "AddressLine1": "Oranienburger Str. 87",
19       "City": "Berlin",
20       "PostalCode": "10178",
21       "Country": "DE"
22     }
23   },
24   "LocalBankTransfer": {
25     "EUR": {
26       "IBAN": "DE75512108001245126199",
27       "BIC": "SOGEDEFFXXX"
28     }
29   },
30   "PendingUserAction": {
31     "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
32   },
33   "RecipientVerificationOfPayee": {
34     "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
35     "RecipientVerificationCheck": "MATCH",
36     "RecipientVerificationMessage": "Account name fully matches account identifier."
37   }
38 }

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 →

Register a bank account for local or international payouts. <Warning icon="fa-regular fa-triangle-exclamation"> **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](/api-reference/recipients/view-recipient-schema) - Check that the user's data is valid using [POST Validate data for a Recipient](/api-reference/recipients/validate-recipient-data) </Warning> <Note icon="fa-regular fa-circle-info"> **Note – SCA triggered by this endpoint** Registering a bank account as a Recipient always requires the user to [authenticate using SCA](/guides/sca/recipients) on a Mangopay-hosted webpage, unless your platform is using a [proxy and user consent](/guides/sca/proxy-management). 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](/guides/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](/api-reference/users/natural-user-object-sca) or the `LegalRepresentative.Email` value of the [Legal User](/api-reference/users/legal-user-object-sca) – for example `accept@example.com` or `john.doe+accept@example.com`. </Note> 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](/webhooks/event-types#recipients) 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](/guides/vop/recipients-payouts) **→**

Authentication

AuthorizationBearer

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.

Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

Path parameters

ClientIdstringRequired

Platform's API account identifier, associated with the API key.

UserIdstringRequired

The unique identifier of the user.

Request

This endpoint expects an object.

International IndividualobjectRequired

Request body for creating a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Individual.

International BusinessobjectRequired

Request body for creating a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Business.

Local IndividualobjectRequired

Request body for creating a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Individual.

Local BusinessobjectRequired

Request body for creating a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Business.

Response

Created

International Individualobject

Response body for a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Individual.

International Businessobject

Response body for a Recipient where PayoutMethodType is InternationalBankTransfer and RecipientType is Business.

Local Individualobject

Response body for a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Individual.

Local Businessobject

Response body for a Recipient where PayoutMethodType is LocalBankTransfer and RecipientType is Business.

Errors

400

Bad Request Error

401

Unauthorized Error