KYC/KYB restriction changes and pay-in beneficiaries

Mangopay is introducing changes to its restrictions on pay-ins and transfers as part of its KYC/KYB obligations. This page aims to describe what’s changing and how your platform needs to respond.

The changes below apply to all platforms in the EEA, who have contracted with Mangopay S.A. and are using Mangopay’s payment services (PS).

Platforms in the UK, contracted with Mangopay U.K. Ltd. and using e-money services (EMS), are not impacted by these pay-in and transfer restriction changes.

Scope

Transactions

The changes described in this page relate to pay-ins and transfers. For pay-ins, the changes impact all payment methods offered by Mangopay.

There are 3 changes being introduced, numbered below: 1 affecting transfers and 2 affecting pay-ins.

The changes do not impact refund flows for either pay-ins or transfers.

Users

The attributes of Natural User and Legal User objects that govern KYC/KYB restrictions are:

• UserCategory – PAYER by default or can become OWNER when the user signs Mangopay’s T&Cs and enrolls in Mangopay’s SCA. KYC/KYB verification can only be requested for OWNER users.
• KYCLevel – LIGHT by default (and for PAYER) and becomes REGULAR when the user successfully completes the KYC/KYB process.

The KYCLevel can be downgraded from REGULAR to LIGHT if KYC/KYB is not renewed periodically or if key identity data is changed.

A downgraded OWNER is subject to the same restrictions – including those below – as one who has not yet been verified. If the User’s KYCLevel is LIGHT, the restriction applies.

Note that for KYC/KYB, Mangopay is also requiring that its hosted KYC/KYB solution be integrated by all platforms.

User categories

Combining the attributes above results in three profiles of Natural or Legal User object that represent your users. All three may hold any number of Mangopay Wallets, and restrictions on any given wallet are based on the User’s status.

There is also fourth profile, designated by the the UserCategory value PLATFORM. This is a Legal User that represents your platform. On these users, the KYCLevel is typically always REGULAR in the API but your platform’s company documentation is also renewed periodically in a separate process.

Note on terminology

Note that the term “beneficiary” in this page refers to a Mangopay Natural or Legal User (with a UserId) targeted by a pay-in. It should not be confused with the same idea in a payout context, where terms like UBO or beneficial owner refer to an individual outside the Mangopay environment who directly or indirectly owns the legal entity receiving a payout.

Dedicated error code

To enforce the changes to transfers and pay-ins, Mangopay is introducing a new ResultCode error for pay-ins and transfers:

• 002951 – Beneficiary OWNER user(s) not KYC verified (KYCLevel is not REGULAR): [list of UserId]

This new error will be returned in the cases described below.

The error message contains the Id of the user (or users in the case of pay-ins, up to 5) that do not meet the restriction criteria. This allows you to identify the user who is not KYC/KYB verified so you can take action accordingly, such as communicating with them.

Transfer changes

The most impactful change taking effect for all platforms is on transfers.

1. Transfer refused to unverified Owner

A transfer will be refused if the CreditedWalletId holder is an OWNER with KYCLevel of LIGHT.

The transfer will fail, meaning its Status becomes FAILED and the ResultCode will be:

• 002951 – Beneficiary OWNER user(s) not KYC verified (KYCLevel is not REGULAR): [list of UserId]

This is consistent with the requirement that Owner users must be KYC/KYB verified before they start payment activities – in this case receiving funds.

A transfer’s DebitedWalletId holder is not taken into account in KYC/KYB checks, so this user can be of any UserCategory and KYCLevel.

There is a new property being introduced on pay-ins, Beneficiaries, but this does not exist on nor apply to transfers.

Integration for pay-ins through Payer wallets

The refusal of transfers to unverified Owners impacts all platforms.

In many cases, the transfer is preceded by a pay-in through the wallet of a Payer.

For backwards compatibility, the pay-in part of this flow can continue as before. The CreditedWalletId is a PAYER, and therefore by definition is not the beneficiary of the pay-in. Therefore, a pay-in to a PAYER can continue as before without action on your part.

Mangopay is introducing a new property, FlowDescriptor.Beneficiaries, which is recommended on all pay-ins, including to Payers. Its purpose is to verify that the beneficiary of the pay-in-plus-transfer flow is KYC/KYB verified before the pay-in takes place.

Until you adopt that property, however, the pay-in can continue. Once the funds arrive on the Payer’s wallet, however, the subsequent transfer will be refused if the targeted Owner is not verified.

This results in two possibilities for your platform, until you adopt the FlowDescriptor.Beneficiaries:

i. Prevent the pay-in (strongly recommended)

You should prevent pay-ins to PAYER wallets if the OWNER targeted by the funds isn’t KYC/KYB verified.

Doing this on your side enables the best experience for the paying user.

If you use the FlowDescriptor.Beneficiaries property to declare the Owner as the beneficiary, and they are not verified, then the pay-in fails with the 002951 error.

The FlowDescriptor.Beneficiaries therefore enforces a rule that you should implement on your side, before the pay-in is initiated.

ii. Allow the pay-in (not recommended)

If you do initiate the pay-in, then it won’t be refused because the CreditedWalletId is a PAYER (the assumes that you haven’t included FlowDescriptor.Beneficiaries).

However, the subsequent transfer to the target Owner will be refused if they are not KYC/KYB verified.

The funds will therefore remain in the Payer’s wallet until one of two outcomes takes place:

1. The Owner is KYC/KYB verified in a timely manner and the transfer can be initiated to finalize the transaction
2. The Owner is not successfully verified in a timely manner, and the pay-in must be refunded

A pay-in to a PAYER wallet remains possible to ensure backwards compatibility with existing flows. However, this flow is not recommended as it may likely result in a poorer experience for paying users.

The FlowDescriptor.Beneficiaries property prevents the funds from entering the system in the first place, and you should therefore adopt it proactively.

Pay-in changes

The changes on pay-ins have particular impact for platforms whose workflow includes pay-ins arriving on wallets held by Owner users.

The changes are applicable to all platforms, even if your platform is only operating pay-ins to PAYER wallets. The FlowDescriptor.Beneficiaries property should be used by all platforms.

The new KYC/KYB restrictions on pay-ins will impact pay-ins to OWNER, so this is the case discussed below.

2. Pay-in refused to unverified Owner…

A pay-in will be refused if the CreditedWalletId holder is an OWNER with KYCLevel of LIGHT.

This will happen if you take no action on these users. The pay-in will fail, meaning its Status becomes FAILED and the ResultCode will be:

• 002951 – Beneficiary OWNER user(s) not KYC verified (KYCLevel is not REGULAR): [list of UserId]

3. … unless you declare the beneficiaries

However, the new FlowDescriptor.Beneficiaries property allows you to declare the beneficiary or beneficiaries of pay-ins that target the wallet of unverified Owners. This is typically useful for models where sellers can also be buyers.

There is a new property on pay-ins: FlowDescriptor.Beneficiaries, which is a list of UserId values.

1
{
2
// ...
3
	"AuthorId": "user_m_01KPAZAN8Z9XQJGVRQ6ZDG3C31",
4
	"CreditedWalletId": "wlt_01KPAZBARZGPMP2S7DD47NNZB1", // Holder's KYC status not checked because Beneficiaries sent
5
  "FlowDescriptor": {
6
    "Beneficiaries": [
7
      {
8
        "UserId": "user_m_02APAYTWSDYXHXN1FRTKX9WMA2" // KYC status checked - must be OWNER with KYC or PLATFORM
9
      },
10
      {
11
        "UserId": "user_m_03KPAYV7MP50YW0XT5DMQQ7N93" // KYC status checked - must be OWNER with KYC or PLATFORM
12
      }
13
    ]
14
  }
15
// ...
16
}

The FlowDescriptor.Beneficiaries declares, two things:

• Firstly, that the pay-in’s CreditedWalletId holder is not the beneficiary. Therefore, Mangopay disregards the status of this user and KYC/KYB checks are not applied to them.
• Secondly, that the Beneficiaries are the users receiving the pay-in funds (after transfer). Therefore, Mangopay applies KYC/KYB checks to ALL users declared in the list. If at least one user is not KYC/KYB verified, then the pay-in fails with the 002951 error.

If you send FlowDescriptor.Beneficiaries, then ALL users declared must have KYCLevel of REGULAR.

Otherwise, the pay-in fails, meaning its Status becomes FAILED and the ResultCode will be:

• 002951 – Beneficiary OWNER user(s) not KYC verified (KYCLevel is not REGULAR): [list of UserId]

Note about preauthorization and recurring flows

There are three cases where the FlowDescriptor.Beneficiaries property is not available on the pay-in but on the object against which the pay-in is requested:

• Preauthorization – 7-day preauthorization for card
• Deposit Preauthorization – 29-day preauthorization for card and PayPal
• Recurring PayIn Registration – Registration object for card, Apple Pay, Google Pay, and PayPal

The FlowDescriptor.Beneficiaries is on these objects because this API call is the moment that the transaction is requested between the AuthorId and the beneficiary, who is either the CreditedWalletId holder or the UserId value(s) you declare.

If before the beneficiary begins payment activities, which includes a pay-in flow requested to them, they must be KYC/KYB verified.

If the CreditedWalletId holder is a PAYER then this user is not the beneficiary (see above for more on this flow).

Integration summary

1. Pay-in where CreditedWalletId is PAYER followed by transfer to target OWNER

2. Pay-in where CreditedWalletId is OWNER

2.1. Followed by a transfer to the target OWNER

2.2. Not followed by another transfer (and therefore a wallet top-up)

All restrictions by transaction type

The tables below give a full breakdown of all restrictions on all transaction types related to KYC/KYB status. The tables show the before and after for EEA platforms using payment services (PS). For UK platforms, there is no change from the previous restrictions.

Pay-ins

If Beneficiaries are not sent

In the API request, if FlowDescriptor.Beneficiaries is null:

• Mangopay checks the CreditedWalletId holder.

For the pay-in to be allowed, the CreditedWalletId holder must be one of the following:

• PAYER
• OWNER whose KYCLevel is REGULAR
• PLATFORM

The pay-in will be refused if the user is an OWNER who has KYCLevel of LIGHT at the time of the API request.

If Beneficiaries are sent

In the API request, if Beneficiaries is sent (and not null):

• Mangopay does not check the CreditedWalletId holder.
• Instead, Mangopay checks ALL the FlowDescriptor.Beneficiaries.UserId values.

For the pay-in to be allowed, ALL UserId values listed in the in the FlowDescriptor.Beneficiaries array must be one of the following:

• OWNER whose KYCLevel is REGULAR
• PLATFORM

The pay-in will be refused if at least one Beneficiaries user is not KYC/KYB verified at the time of the API request.

Transfer

The beneficiaries concept does not exist on transfers.

Crediting a wallet (transfer in)

In the transfer API request:

• Mangopay checks the CreditedWalletId holder.

For the transfer to be allowed, the CreditedWalletId holder must be one of the following:

• OWNER whose KYCLevel is REGULAR
• PLATFORM

The transfer will be refused if the user is not KYC/KYB verified at the time of the API request.

Debiting a wallet (transfer out)

On a transfer, Mangopay only checks the CreditedWalletId holder. The DebitedWalletId is not taken into account.

No changes to payouts

For completeness, the existing KYC/KYB limits are presented below. There is no change in KYC/KYB restrictions on these features.

Payouts

The KYC/KYB limits on payouts are not changing. In the EEA, a user must be KYC/KYB verified to request a payout.

FAQ

Does this apply to all pay-ins?

Yes. All payment methods (cards flows, APMs, etc.) should to have beneficiary users declared.

In almost all cases, this means identifying the pay-in beneficiaries and sending their UserId values in the FlowDescriptor.Beneficiaries on the API request of the existing POST endpoint (as described above).

In the case of pay-ins to virtual accounts and bank wire pay-ins and, there will be additional changes required to accommodate the declaration of pay-in beneficiaries (see below).

What about Virtual Account pay-ins?

When funds arrive on the IBAN or account number of a Virtual Account, Mangopay credits the associated wallet and creates the pay-in.

In the current flow, therefore, there is no pay-in API call where your platform can declare beneficiaries.

Mangopay will be introducing new API endpoints which allow you to:

1. Pre-declare the beneficiaries before the funds arrive:
   • You declare the pay-in in advance, including the FlowDescriptor.Beneficiaries.
   • When the funds arrive, Mangopay reconciles them based on the pay-in Amount and optional WireReference
   • Mangopay credits the wallet.
2. Declare the beneficiaries when the funds arrive:
   • When the funds arrive, Mangopay sends a webhook notification but doesn’t credit the wallet.
   • Based on the webhook, your integration sends the FlowDescriptor.Beneficiaries.
   • Mangopay credits the wallet.

What about classic bank wires?

For bank wire pay-ins (that are not Virtual Account pay-ins), the FlowDescriptor.Beneficiaries will need to be included in the pay-in declaration call (see details on current flow).

Mangopay is developing a new endpoint on which both bank wire and Virtual Account pay-ins can be declared. The pay-in object will also be unified to improve and harmonize the bank transaction data returned to your platform. This means there will be a new POST endpoint, and that the object you retrieve via the GET endpoint will have a slightly different structure. The overall operation will be the same (but with beneficiaries sent in the POST, as for all other payment methods).

What about Checkout SDK?

Platforms using Checkout SDK need to send the parameter in their backend API calls.

How many target beneficiaries can be declared?

Mangopay anticipates that up to 5 beneficiaries may need to be declared, in cases where a single pay-in is subsequently split in multiple transfers. This may happen in the case of a mixed basket on a marketplace, for example, where a buyer makes a purchase from multiple sellers.

What about technical users?

In some workflows, there may be a specified user (typically a PAYER) that does not represent an individual or entity but whose sole purpose is to technically enable or facilitate your approved workflow. For example, a technical user and wallet may be used to receive a direct settlement from a third-party PSP.

Although these users usually receive pay-ins to be dispatched elsewhere, because they are known and approved by Mangopay, they do not require beneficiaries to be declared.

What about Platform users?

For your platform’s workflow, Mangopay may have approved a dedicated user that represents your platform and assigned it the UserCategory value PLATFORM.

The PLATFORM user may need to be specified in the FlowDescriptor.Beneficiaries of the pay-in request in the same way as any other beneficiary.

Pay-ins transiting the wallet of the PLATFORM user would require the FlowDescriptor.Beneficiaries to be specified.

What about Echo?

If your platform is working with a third-party PSP, Mangopay’s Echo solution allows you to declare the Mangopay Users that are the beneficiaries of flows processed by your partner.

If your platform is using a third-party PSP as well as Mangopay for acquisition, then the FlowDescriptor.Beneficiaries will need to be declared on the Mangopay pay-in requests. Your Echo integration will be used to declare the third-party flows.

What about the Mirakl Connector?

Platforms using the Mirakl Connector along with Mangopay for pay-ins (and no third-party PSP) do not need to declare the FlowDescriptor.Beneficiaries in their pay-in requests.

Platforms using the Mirakl Connector with Echo declare the beneficiaries via Echo.

Does this affect payouts?

No. The payout stage of your users’ payment activity is not impacted by these changes.