API - June 24, 2026

Added

FlowDescriptor for declaring pay-in Beneficiaries

The FlowDescriptor.Beneficiaries request property has been added to pay-ins for all payment methods. The FlowDescriptor.Beneficiaries is an array of objects each containing only the UserId property. Up to 5 UserId objects can be listed in the array.

In the case of preauthorizations, deposit preauthorizations, and recurring pay-in registrations (for all payment methods), the property has been added to these objects instead of the pay-ins requested against them.

Purpose

This property serves to identify the UserId values that are the beneficiaries of the pay-in and its subsequent transfers.

It is optional for backwards compatibility with existing flows.

However, in all cases your platform is strongly encouraged to:

1. Prevent pay-ins from being initiated if the Owner user(s) ultimately targeted by the pay-in (and its subsequent transfers) is not KYC/KYB verified
2. Adopt the FlowDescriptor.Beneficiaries property to proactively declare the Owner user(s) whose KYC/KYB status should be checked by Mangopay

If you do not send the FlowDescriptor.Beneficiaries property, then the KYC/KYB checks are performed on the CreditedWalletId holder.

Adopting this property therefore allows your platform to:

• Ensure that no pay-ins enter the Mangoapy environment if the declared beneficiary of the funds is not KYC/KYB verified
• Accommodate pay-ins that transit unverified Owners, such as in P2P marketplaces models where sellers may also need to be able to make purchases before they are themselves verified

KYC/KYB verification logic on pay-ins

The logic Mangopay will apply to KYC/KYB verification on pay-ins is outlined below.

If FlowDescriptor.Beneficiaries is sent in the API request

If the FlowDescriptor.Beneficiaries is sent in the API request (so is not null), then:

• The CreditedWalletId holder is disregarded in KYC/KYB checks
• ALL UserId values listed must be one of:
  • OWNER whose KYCLevel is REGULAR
  • PLATFORM

If ANY FlowDescriptor.Beneficiaries.UserId is:

• PAYER
• OWNER whose KYCLevel is LIGHT

Then the pay-in will fail with the ResultCode 002951.

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
}

If FlowDescriptor.Beneficiaries is not sent in the API request

If FlowDescriptor.Beneficiaries are not declared on the pay-in (so isnull), then the holder of the CreditedWalletId is subject to KYC/KYB checks and must be one of the following:

• PAYER
• OWNER whose KYCLevel is REGULAR
• PLATFORM

For more details, see the dedicated guide

Added

Error 002951 for KYC/KYB restrictions on pay-ins and transfers

A new ResultCode and ResultMessage can be returned for pay-ins and transfers attempts that do not comply with the new KYC/KYB restrictions:

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

The error message contains the UserId value or values (up to 5 in the case of pay-in beneficiaries) whose KYC/KYB status is preventing the transaction from being initiated.

In the cases below, this code will be returned and the pay-in or transfer Status will become FAILED.

1. Pay-in to unverified Owner without verified Beneficiaries

The error is returned on a pay-in request if:

• The CreditedWalletId holder is:
  • OWNER whose KYCLevel is LIGHT
• AND the new FlowDescriptor.Beneficiaries is null (because its not sent)

2. Pay-in with Beneficiaries that aren’t verified

The error is also returned on a pay-in request if:

• FlowDescriptor.Beneficiaries is sent (not null)
• AND at least one UserId listed is:
  • PAYER
  • OWNER whose KYCLevel is LIGHT

3. Transfer to unverified Owner

The error is returned on a transfer request if:

• The CreditedWalletId holder is:
  • PAYER
  • OWNER whose KYCLevel is LIGHT

The Beneficiaries property is not available on transfers and does not apply.

For more details, see the dedicated guide: