Read about Mangopay’s new Recipients feature, replacing bank accounts
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.
RecipientScope
is PAYOUT
, see below).
SCA redirection is required each time a user registers a new recipient bank account, even if they are registering them one after another.
All payout currencies are available in Recipients in Production and Sandbox.
BankAccountId
of active bank accounts remains the same (and be returned in the RecipientId
field).
All active legacy bank accounts have been migrated, including those used for direct debits and pay-in refunds (see pay-in scope below).
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.
PAYER
(or OWNER
) in two specific pay-in scenarios that are out of scope of Mangopay’s SCA feature:
PAYIN_REFUND
reference of the initial pay-in, read more)RecipientScope
value PAYIN
, can be created for a user with the UserCategory
PAYER
or OWNER
, and does not require SCA.
RecipientType
. For individuals, the first and last name and address are required; for businesses, the business name and address.
AED
, AUD
, CAD
, CHF
, CNH
, CZK
, DKK
, EUR
, GBP
, HKD
, HUF
, ILS
, JPY
, MXN
, NOK
, NZD
, PLN
, RON
, SAR
, SEK
, SGD
, TRY
, USD
, ZAR
Depending on the Country
value queried on GET View payout methods, the API returns one (or both) of the AvailablePayoutMethods
offered by Mangopay:
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
and destination Country
of the payout.InternationalBankTransfer
payout method type, because that is the available payout method for that route.
On international payouts, if a country uses IBAN then the AccountNumber
is the local IBAN format and the returned BIC is generated from the IBAN. For countries that don’t use IBAN, the AccountNumber
format depends on the Country
and the BIC
is also required. So in the CAD to US example, the AccountNumber
must be a US account identifier and the BIC
is required.
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.
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.
RecipientScope
is PAYOUT
(or not sent)OWNER
(which is necessary for the RecipientScope
PAYOUT
)RecipientScope
is PAYIN
LegalPersonType
is BUSINESS
, ORGANIZATION
, or PARTNERSHIP
PAYER
ClientId
and API key.
OWNER
user, follow the steps below. In the payout scenario described below, RecipientScope
is PAYOUT
(by default) and therefore SCA is required.
View available payout methods
Fetch the data schema
Validate the user's recipient data
Create the recipient
Status
as PENDING
and contains the PendingUserAction.RedirectUrl
you need for the next step.Redirect the user to the SCA session
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.Confirm the outcome
controlStatus
query parameter.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, create a new Recipient by calling the POST Create a Recipient endpoint again to obtain another RedirectUrl
for a new SCA session.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
(but the PAYIN
value is allowed if the payout is serving as a refund and specifies a PaymentRef
)PENDING
(for example, if SCA is in progress) or CANCELED
(if SCA is not successful), then the Recipient ID is not considered valid and a 400 error is returned:
DEACTIVATED
, the payout is created with FAILED
status and the ResultCode
121006 (The associated bank account is not active).
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 successfully completed, 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.RECIPIENT_ACTIVE
RECIPIENT_CANCELED
RECIPIENT_DEACTIVATED