> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# 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.

#### See list of endpoints with \`FlowDescriptor.Beneficiaries\` available

* [POST Create a Direct Card PayIn](/api-reference/direct-card-payins/create-direct-card-payin)
* [POST Create a Recurring PayIn Registration](/api-reference/recurring-payin-registrations/create-recurring-payin-registration) (all `PaymentType`)
* [POST Create a Preauthorization](/api-reference/preauthorizations/create-preauthorization)
* [POST Create a Card Deposit Preauthorization](/api-reference/extended-preauthorizations/create-card-extended-preauthorization)
* [POST Create a PayPal Deposit Preauthorization](/api-reference/extended-preauthorizations/create-paypal-extended-preauthorization)
* [POST Create a Web Card PayIn](/api-reference/web-card-payins/create-web-card-payin)
* [POST Create a Bank Wire PayIn](/api-reference/bank-wire-payins/create-bank-wire-payin)
* [POST Create a Direct Debit PayIn](/api-reference/direct-debit-payins/create-direct-debit-payin)
* [POST Create a Web Direct-Debit PayIn](/api-reference/web-direct-debit-payins/create-web-direct-debit-payin)
* [POST Create an Apple Pay PayIn](/api-reference/apple-pay/create-apple-pay-payin)
* [POST Create a Bancontact PayIn](/api-reference/bancontact/create-bancontact-payin)
* [POST Create a Bizum PayIn](/api-reference/bizum/create-bizum-payin)
* [POST Create a BLIK PayIn (with and without code)](/api-reference/blik/create-blik-payin)
* [POST Create a Google Pay PayIn](/api-reference/google-pay/create-google-pay-payin)
* [POST Create an iDEAL PayIn](/api-reference/ideal/create-ideal-payin)
* [POST Create a Klarna PayIn](/api-reference/klarna/create-klarna-payin)
* [POST Create an MB WAY PayIn](/api-reference/mb-way/create-mb-way-payin)
* [POST Create a Multibanco PayIn](/api-reference/multibanco/create-multibanco-payin)
* [POST Create a Pay by Bank PayIn](/api-reference/pay-by-bank/create-pay-by-bank-payin)
* [POST Create a Payconiq PayIn](/api-reference/payconiq/create-payconiq-payin)
* [POST Create a PayPal PayIn](/api-reference/paypal/create-paypal-payin)
* [POST Create a Satispay PayIn](/api-reference/satispay/create-satispay-payin)
* [POST Create a Swish PayIn](/api-reference/swish/create-swish-payin)
* [POST Create a TWINT PayIn](/api-reference/twint/create-twint-payin)

#### 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](/errors/codes/002951).

**`Example pay-in API request with Beneficiaries declared`**

```json Example pay-in API request with Beneficiaries declared
{
// ...
  "AuthorId": "user_m_01KPAZAN8Z9XQJGVRQ6ZDG3C31",
  "CreditedWalletId": "wlt_01KPAZBARZGPMP2S7DD47NNZB1", // Holder's KYC status not checked because Beneficiaries sent
  "FlowDescriptor": {
    "Beneficiaries": [
      {
        "UserId": "user_m_02APAYTWSDYXHXN1FRTKX9WMA2" // KYC status checked - must be OWNER with KYC or PLATFORM
      },
      {
        "UserId": "user_m_03KPAYV7MP50YW0XT5DMQQ7N93" // KYC status checked - must be OWNER with KYC or PLATFORM
      }
    ]
  }
// ...
}
```

##### If `FlowDescriptor.Beneficiaries` is **not** sent in the API request

\


If `FlowDescriptor.Beneficiaries` are **not** declared on the pay-in (so is`null`), 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

#### [Guide](/guides/payin-beneficiaries)

KYC/KYB restriction changes and declaring pay-in beneficiaries

> **Warning**
>
> **Caution – Prevent pay-ins through Payer wallets if Owner is not KYC/KYB verified**
>
> In some workflows, a pay-in transits the wallet of a `PAYER` user before being transferred to an `OWNER`.
>
> These pay-ins continue to be allowed to ensure backwards compatibility, but the transfer will be refused if the `OWNER` is not yet KYC/KYB verified or has been downgraded to `LIGHT`.
>
> This will result in a delay in the transaction (until the `OWNER` is verified), or the need for a refund.
>
> You are therefore very strongly recommended to prevent these pay-ins from being initiated in the first instance.
>
> The `FlowDescriptor.Beneficiaries` property allows you to declare the beneficiaries when the pay-in is initiated, thus ensuring that no pay-ins enter without a KYC/KYB-verified beneficiary.
>
> Read more about the specific impact on [pay-ins through Payer wallets](/guides/payin-beneficiaries#integration-for-pay-ins-through-payer-wallets) **→**

---

## 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](/errors/codes/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:

#### [Guide](/guides/payin-beneficiaries)

KYC/KYB restriction changes and declaring pay-in beneficiaries