KYC Rejection Troubleshooting

When a user's onboarding task is rejected, its status is set to FAILED and a rejectionReason field is included. This guide covers common rejection scenarios and how to resolve them.


Detecting a rejection

There are two ways to detect a rejected task:

  1. Webhook — Listen for the USER_ONBOARDING_UPDATE event. When a task changes to FAILED, the rejectionReason field in the onboarding object describes the issue.
  2. API polling — Call GET /v2/users/:userAnyId and inspect the onboarding object for tasks with status: "FAILED".
{
  "onboarding": {
    "IDENTITY_VALIDATION": {
      "required": true,
      "status": "FAILED",
      "rejectionReason": "3. La foto del DNI se ve borrosa o sin nitidez"
    }
  }
}

The rejectionReason format

rejectionReason follows the format "<index>. <description>":

  • The leading number up to the first dot is a stable error index — it always maps to the same rejection cause, so you can use it as a key for your own localized messages. The catalogs below list every index.
  • The description after the index is human-readable text in Spanish, written for compliance review. It is not a machine-readable code — use the index for programmatic handling and treat the text as supporting detail.
  • Some rejections (e.g. PEP/FEP documentation reviewed manually) may carry free text without an index. Handle a missing index gracefully by showing a generic "resubmit" message for that task.
  • If SECURITY_VALIDATION fails, no rejection reason is exposed for regulatory reasons and the user is set to INACTIVE — contact support.

Rejection reason catalogs

Identity Validation (IDENTITY_VALIDATION)

These rejections occur after identity document images are submitted.

IndexReason (Spanish, as received)English translationHow to resolve
1Sin comentariosNo commentsGeneric rejection — re-upload both sides with good lighting
2El DNI no se encuentra centrado en la imagenThe ID is not centered in the imageRe-take the photo with the full document centered in frame
3La foto del DNI se ve borrosa o sin nitidezThe ID photo is blurry or lacks sharpnessRe-upload a sharper photo with good lighting
4El DNI subido no corresponde con la información del usuario o está vencido, o no es el ejemplar correctoThe uploaded ID does not match the user's declared information, is expired, or is not the correct copy of the documentVerify legalId and personal data match the document, and that it is valid and current
5Se subio la misma foto para frente y dorso del DNIThe same photo was uploaded for both the front and the back of the IDUpload the correct image for each side (FRONT / BACK)
6El DNI está siendo tapado por un objeto o la mano del usuarioThe ID is partially covered by an object or the user's handRe-take the photo with the whole document visible
7Tipo de DNI no validoInvalid ID document typeUse the accepted document type for the user's country
8El DNI enviado esta próximo a vencerThe submitted ID is close to its expiry dateUpload a document with a longer validity period

Selfie Validation (SELFIE_VALIDATION)

IndexReason (Spanish, as received)English translationHow to resolve
1Sin comentariosNo commentsGeneric rejection — re-upload a clear, front-facing selfie
2No coincide DNI con la fotoThe ID does not match the photoUpload a selfie of the same person as the submitted ID
3La foto SELFIE no tiene un formato válidoThe selfie photo does not have a valid formatRe-upload in an accepted image format (e.g. JPG/PNG)
4La foto SELFIE debe tener documento en mano que sea visibleThe selfie must show the document in hand, clearly visibleRe-take the selfie holding the ID next to the face, readable

Basic Personal Data (BASIC_PERSONAL_DATA_DEFINITION)

Rejections of personal data are not indexed — the rejectionReason describes the offending field(s). Re-submit the corrected data using POST /v2/onboarding-actions/define-personal-data.


How to resubmit after a rejection

When a task is FAILED, it can be retried by calling the same onboarding action endpoint again with corrected data or new files.

1
Check the rejection reason

Read the rejectionReason from the webhook payload or the GET /v2/users/:userAnyId response.

2
Fix the issue

Ask the user to provide a new document image, corrected data, or a clearer selfie — depending on the rejection reason.

3
Resubmit the task

Call the same onboarding action endpoint again. The task status will reset and the validation process restarts. A new USER_ONBOARDING_UPDATE webhook will be sent when the resubmission is processed.


Relevant endpoints for resubmission


Impact on user operations

While a required task is FAILED, the user remains in ONBOARDING status and cannot operate on the platform. Once the task is resubmitted and approved, the user can resume the onboarding process.

If an onboarding task is rejected and not corrected, the user will not reach ACTIVE status. Monitor failed tasks and prompt users to resubmit promptly.


Expired tasks

Some completed tasks may transition to EXPIRED over time — for example, an identity document that reached its expiration date. Expired tasks must be resubmitted using the same endpoint as the original submission. The user remains ACTIVE during the resubmission window but may be restricted if the expired task is not renewed.


When to contact Manteca support

Most rejections can be resolved by resubmitting through the API. Contact Manteca support when:

  • The rejection reason is unclear or not listed above
  • The user has been rejected multiple times with correct documentation
  • The user's status has changed to INACTIVE and you need to understand why

Related pages


Did this page help you?