ResourcesError handlingError codes

002951

Error messageBeneficiary OWNER user(s) not KYC verified (KYCLevel is not REGULAR): [list of UserId]
Description

The transaction was refused because a targeted user is not an OWNER whose KYCLevel is REGULAR (or a PLATFORM user). The unverified user may be the CreditedWalletId holder or (on a pay-in, if declared) a FlowDescriptor.Beneficiaries.UserId.

Categories
Pay-ins

Transfers

Causes

This error is triggered by KYC/KYB restrictions on pay-ins and transfers.

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

Note – Error may be caused by non-renewal or downgrade

In the case of users with UserCategory of OWNER, KYC/KYB restrictions apply to users who are not yet verified for the first time as well as those who were previously verified but have been downgraded.

A KYC/KYB downgrade, where Mangopay changes the KYCLevel from REGULAR to LIGHT, may occur for two reasons:

  • The KYC/KYB process was not completed before the KycRenewalDeadline as per the periodic KYC/KYB verification renewal
  • Key identity-related data points were changed in the User object, triggering a downgrade

There are three cases when the transaction can become FAILED with the 002951 ResultCode:

1. Pay-in to unverified Owner without FlowDescriptor.Beneficiaries declared

The error is returned on a pay-in (or recurring pay-in registration, preauthorization, or deposit preauthorization) if:

  • The CreditedWalletId holder is (UserCategory of):
    • OWNER whose KYCLevel is LIGHT
  • AND the 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 (or recurring pay-in registration, preauthorization, or deposit preauthorization) if:

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

3. Transfer to unverified Owner

The error is returned on a transfer request if:

  • The CreditedWalletId holder is (UserCategory of):
    • PAYER
    • OWNER whose KYCLevel is LIGHT

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

Read more about the KYC/KYB restrictions on transfers and pay-ins →

What to do

If this error is triggered:

  • Retrieve the UserId values from the error message
  • Invite the user to complete their KYC/KYB verification, using the hosted KYC/KYB solution (or the legacy API-based solution)
  • Once complete (ensure their KYCLevel is REGULAR), retry the transaction