Skip to main content
POST
/
v2.01
/
{ClientId}
/
users
/
{UserId}
/
recipients
{
    "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"
        }
    }
}
{
    "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
    "Status": "PENDING",
    "CreationDate": 1759228005,
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {
            "IBAN": "DE75512108001245126199",
            "BIC": "SOGEDEFFXXX"
        }
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
    },
    "RecipientVerificationOfPayee": {
        "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
        "RecipientVerificationCheck": "MATCH",
        "RecipientVerificationMessage": "Account name fully matches account identifier."
    }
}
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:
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.
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. Verification of Payee (VOP) impacts SEPA local schemes, which means Recipients with Currency value EUR and PayoutMethod value LocalBankTransfer. Read more

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

  • InternationalBankTransfer
  • LocalBankTransfer
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

Id
string
Max length: 128 characters (see data formats for details)The unique identifier of the object.
Status
string
Possible values: PENDING, CANCELED, ACTIVE, DEACTIVATEDThe status of the recipient:
  • PENDING – For PAYOUT scope recipients, the user must complete SCA before the recipient can become ACTIVE. For PAYIN 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 another PendingUserAction.RedirectUrl. The CANCELED status does not apply if RecipientScope is PAYIN.
  • ACTIVE – Recipient creation was successful (including SCA if RecipientScope is PAYOUT) and the recipient is ready to be used for payouts .
  • DEACTIVATED – The recipient has been permanently deactivated and can no longer be used.
CreationDate
Unix timestamp
The date and time at which the object was created.
DisplayName
string
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
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
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
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
Format: Two-letter country code (ISO 3166-1 alpha-2 format)The destination country of the payout method.
UserId
string
The unique identifier of the user.
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.
Both PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.
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.
UserId
string
The unique identifier of the user.
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.
Both PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.
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.
  • Individual
  • Business
IndividualRecipient
object
The account holder if the RecipientType is Individual.

  • InternationalBankTransfer
  • LocalBankTransfer
InternationalBankTransfer
object
The account details if PayoutMethodType is InternationalBankTransfer.
PendingUserAction
object
Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned null).
RecipientVerificationOfPayee
object
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.
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_FOUNDClientId making the request does not exist.
  • USER_NOT_FOUNDUserId 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.
{
    "Id": "rec_01K6D2J3683015F5D3M81JEXRH",
    "Status": "PENDING",
    "CreationDate": 1759228005,
    "DisplayName": "John Doe EUR DE account",
    "PayoutMethodType": "LocalBankTransfer",
    "RecipientType": "Individual",
    "Currency": "EUR",
    "Country": "DE",
    "UserId": "user_m_01K5Y4XQA9HESYF8S9V70K16XH",
    "RecipientScope": "PAYOUT",
    "Tag": "Created using the Mangopay API Postman collection",
    "IndividualRecipient": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": {
            "AddressLine1": "Oranienburger Str. 87",
            "City": "Berlin",
            "PostalCode": "10178",
            "Country": "DE"
        }
    },
    "LocalBankTransfer": {
        "EUR": {
            "IBAN": "DE75512108001245126199",
            "BIC": "SOGEDEFFXXX"
        }
    },
    "PendingUserAction": {
        "RedirectUrl": "https://sca.sandbox.mangopay.com/?token=sca_01999a290f06700b992580d3450609a0"
    },
    "RecipientVerificationOfPayee": {
        "RecipientVerificationId": "46fa0ccc-6cb0-4874-95ba-9edbc6cf7904",
        "RecipientVerificationCheck": "MATCH",
        "RecipientVerificationMessage": "Account name fully matches account identifier."
    }
}
{
    "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"
        }
    }
}