​
Introduction

Mangopay is releasing a new version of the Bank Account object called Recipients.

When a Mangopay Account holder (OWNER) registers an external bank or payment account, the account holder must authenticate using SCA.

As well as supporting SCA, Recipients enable faster and more reliable local and international payouts.

The new set of Recipient endpoints replaces the legacy Bank Account endpoints, including bank account types.

In the Recipients feature, each local and international account has a specified data schema which your platform has to retrieve in advance of requesting the details from the user. Once you have the user’s details, you are also able to check that they are valid before creating the Recipient.

In this way, the Recipients feature helps ensure that payouts are delivered effectively.

Once Recipients is fully live in Production in May 2025, existing bank accounts will be compatible with the new Recipients feature. This means your platform will be able to continue using the BankAccountId of active bank accounts for payouts, as well as for direct debits and pay-in refunds.

​
Recipient scopes

​
Payout

By default, the Recipient is considered to be for use with payouts. This is indicated by the RecipientScope parameter which has the default value PAYOUT.

This kind of recipient can only be registered by an OWNER user and can be used for payouts. SCA is always required when the Recipient is created, so the API call returns the PendingUserAction.RedirectUrl and the individual must authenticate on the Mangopay-hosted webpage.

Because the Recipient registration was authenticated with SCA, it can be considered a trusted beneficiary for future payouts. This allows the payout to be initiated without SCA, but the usual KYC verification requirements apply.

A recipient with the PAYOUT scope can also be used for the pay-in use cases of the PAYIN scope (direct debits and refunds, described below), but not the other way around.

​
Pay-in

A Recipient may be needed for a PAYER (or OWNER) in two specific pay-in scenarios that are out of scope of Mangopay’s SCA feature:

  • Direct debit pay-ins (SEPA and Bacs)
  • Pay-in refunds that technically use payouts (specifying the PAYIN_REFUND reference of the initial pay-in, read more)

This kind of recipient, with the RecipientScope value PAYIN, can be created for a user with the UserCategory PAYER or OWNER, and does not require SCA.

​
SCA triggers in Sandbox

In Sandbox, SCA is triggered on POST Create a Recipient when all of the following are true:

  • RecipientScope is PAYOUT (or not sent)
  • The user’s type is Natural or Soletrader
  • The user is an OWNER (which is necessary for the RecipientScope PAYOUT)

In Sandbox, SCA is not triggered if any of the following are true:

  • RecipientScope is PAYIN
  • The Legal user’s LegalPersonType is BUSINESS, ORGANIZATION, or PARTNERSHIP
  • The user is a PAYER

​
Recipient types

A Recipient represents the beneficiary and the beneficiary account of a payout. A recipient can be an individual or a business, indicated by the RecipientType. For individuals, the first and last name and address are required; for businesses, the business name and address.

​
Payout methods

Mangopay offers two payout methods:

  • InternationalBankTransfer – A bank wire sent via the global messaging network SWIFT.
  • LocalBankTransfer – A bank wire sent via a national domestic route. The account details required for local payouts change depending on the Currency of the payout.

You can call the GET View payout methods endpoint to find out which payout method is available for a given country and currency.

Based on the payout method, you can register the user’s bank account as a Recipient to receive payouts.

For example, if the user’s account is registered in the US and the payout currency is CAD, then they need a recipient with the InternationalBankTransfer payout method type, because that is the available payout method for that route. Registering the recipient requires the account’s IBAN.

However, if the user’s bank account is registered in the UK and the payout currency is GBP, then they need a recipient with the LocalBankTransfer payout method type. In this case, registering the recipient requires the UK account number and sort code.

To know exactly which details are required to register the account, call the GET View the schema for a Recipient:

  • AUD – Account number, branch-state-branch (BSB) number
  • CAD – Account number, institution number, branch code, bank name
  • EUR – IBAN
  • GBP – Account number, sort code
  • HKD – Account number, BIC, branch code
  • SGD – Account number, BIC
  • USD – Account number, ABA routing number

For international payouts, the IBAN is required for all currencies.

Each recipient can be used for one combination of a payout method and currency, which together determine the account details required.

A user’s real bank account can therefore be registered more than once, for example in one recipient in the local format and another in the international format.

​
How to register a recipient for payouts

To register a recipient for payouts for an OWNER user, follow the steps below. In the payout scenario described below, RecipientScope is PAYOUT (by default) and therefore SCA is required.

1

View available payout methods

Call the GET View payout methods endpoint to find out which payout methods are available to your platform in each currency and destination country.

2

Fetch the data schema

Call the GET View the schema for a Recipient endpoint to know the data required to create the recipient based on the country, currency, and payout method.

Best practice – Retrieve schema before requesting user data

The schema for a recipient may change, so you should integrate dynamic retrieval of all fields (account details, holder data, etc) before presenting them to the user.

3

Validate the user's recipient data

Check that the user’s data is valid by submitting it to the POST Validate data for a Recipient endpoint.

A 200 - OK response indicates that the format is correct against the schema and that the data is valid. If one or more data field does not conform to the schema, then a 400 error is returned listing the errors.

Best practice – Validate data before creation

You are strongly recommended to validate the recipient data before creating it. This helps avoid payouts being rejected and optimizes deliverability.

4

Create the recipient

Once validated, call the POST Create a Recipient endpoint with the same request body to register the account details.

The 201 - Created response from the API shows the recipient’s Status as PENDING and contains the PendingUserAction.RedirectUrl you need for the next step.

5

Redirect the user to the SCA session

Define a URL to which the user will be redirected after the SCA session. Encode the URL and append it to the RedirectUrl value as the returnUrl query parameter (for details see How to redirect a user for an SCA session (Step 2 onwards)). Then, redirect the user.

6

Confirm the outcome

When the user is returned after the SCA session, you can check the status of the indicative controlStatus and actionStatus query parameters.

The Recipient Status is PENDING until the user authenticates successfully, at which point it changes to ACTIVE.

Set up a webhook for the RECIPIENT_ACTIVE event type to be notified of this.

Call the GET View a Recipient endpoint to check its status.

If SCA is not successfully completed, the status changes to CANCELED. To retry SCA, call the POST Create a Recipient endpoint again to obtain another RedirectUrl for a new SCA session.

​
How to initiate a payout

Note – Legacy bank accounts can continue to be used for payouts

Existing active bank accounts are compatible with the Recipients feature and can continue to be used for payouts.

Once Recipients is fully live in Production in May 2025, existing bank accounts will also be available via the Recipient endpoints, such as GET View a Recipient.

When the Status of a Recipient is ACTIVE, you can request a payout to it by calling the POST Create a Payout endpoint and entering the Id of the Recipient as the BankAccountId.

Payouts can only be requested against a Recipient that has:

  • Status value ACTIVE
  • RecipientScope value PAYOUT

If you attempt a payout to a Recipient that is PENDING or CANCELED, the Recipient ID is not considered valid and a 400 error is returned:

{
    "Id": "0602decd-c7e4-4870-a103-1ac242b23467#1739868259",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1739868260,
    "errors": {
        "BankAccountId": "The value rec_01JM1X5ZF868NYBZDF9MCB6VWE is not valid"
    }
}

If you attempt a payout to a Recipient that is DEACTIVATED, the payout is created with FAILED status and the ResultCode 121006 (The associated bank account is not active).

​
Status and webhooks

The Status of the Recipient can have the following values.

  • PENDING – When a Recipient is first created, it has the PENDING status. The user must complete SCA before the recipient can become ACTIVE and be used.
  • CANCELED – If SCA is not successful, the Recipient status changes to CANCELED and is permanently disabled. To retry the registration of the recipient, create another recipient to retrieve another PendingUserAction.RedirectUrl.
  • ACTIVE – SCA was successful and the Recipient was created successfully. Payouts can only be requested to a Recipient that is ACTIVE.
  • DEACTIVATED – The recipient has been permanently disabled and can no longer be used for payouts. You can deactivate a Recipient using the PUT Deactivate a Recipient endpoint.

The following event types are available for webhook notifications:

  • RECIPIENT_ACTIVE
  • RECIPIENT_CANCELED
  • RECIPIENT_DEACTIVATED

Endpoints

See the Recipient object and endpoints

Guide

Read more about redirecting for SCA in each SCA-scenario

Was this page helpful?