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:
- Webhook — Listen for the
USER_ONBOARDING_UPDATEevent. When a task changes toFAILED, therejectionReasonfield in the onboarding object describes the issue. - API polling — Call
GET /v2/users/:userAnyIdand inspect theonboardingobject for tasks withstatus: "FAILED".
{
"onboarding": {
"IDENTITY_VALIDATION": {
"required": true,
"status": "FAILED",
"rejectionReason": "3. La foto del DNI se ve borrosa o sin nitidez"
}
}
}The rejectionReason format
rejectionReason formatrejectionReason 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_VALIDATIONfails, no rejection reason is exposed for regulatory reasons and the user is set toINACTIVE— contact support.
Rejection reason catalogs
Identity Validation (IDENTITY_VALIDATION)
IDENTITY_VALIDATION)These rejections occur after identity document images are submitted.
| Index | Reason (Spanish, as received) | English translation | How to resolve |
|---|---|---|---|
| 1 | Sin comentarios | No comments | Generic rejection — re-upload both sides with good lighting |
| 2 | El DNI no se encuentra centrado en la imagen | The ID is not centered in the image | Re-take the photo with the full document centered in frame |
| 3 | La foto del DNI se ve borrosa o sin nitidez | The ID photo is blurry or lacks sharpness | Re-upload a sharper photo with good lighting |
| 4 | El DNI subido no corresponde con la información del usuario o está vencido, o no es el ejemplar correcto | The uploaded ID does not match the user's declared information, is expired, or is not the correct copy of the document | Verify legalId and personal data match the document, and that it is valid and current |
| 5 | Se subio la misma foto para frente y dorso del DNI | The same photo was uploaded for both the front and the back of the ID | Upload the correct image for each side (FRONT / BACK) |
| 6 | El DNI está siendo tapado por un objeto o la mano del usuario | The ID is partially covered by an object or the user's hand | Re-take the photo with the whole document visible |
| 7 | Tipo de DNI no valido | Invalid ID document type | Use the accepted document type for the user's country |
| 8 | El DNI enviado esta próximo a vencer | The submitted ID is close to its expiry date | Upload a document with a longer validity period |
Selfie Validation (SELFIE_VALIDATION)
SELFIE_VALIDATION)| Index | Reason (Spanish, as received) | English translation | How to resolve |
|---|---|---|---|
| 1 | Sin comentarios | No comments | Generic rejection — re-upload a clear, front-facing selfie |
| 2 | No coincide DNI con la foto | The ID does not match the photo | Upload a selfie of the same person as the submitted ID |
| 3 | La foto SELFIE no tiene un formato válido | The selfie photo does not have a valid format | Re-upload in an accepted image format (e.g. JPG/PNG) |
| 4 | La foto SELFIE debe tener documento en mano que sea visible | The selfie must show the document in hand, clearly visible | Re-take the selfie holding the ID next to the face, readable |
Basic Personal Data (BASIC_PERSONAL_DATA_DEFINITION)
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.
Read the rejectionReason from the webhook payload or the GET /v2/users/:userAnyId response.
Ask the user to provide a new document image, corrected data, or a clearer selfie — depending on the rejection reason.
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
| Rejected task | Resubmit with |
|---|---|
IDENTITY_VALIDATION | POST /v2/onboarding-actions/upload-identity-image |
SELFIE_VALIDATION | POST /v2/onboarding-actions/upload-selfie-image |
BASIC_PERSONAL_DATA_DEFINITION | POST /v2/onboarding-actions/define-personal-data |
PEP_DOCUMENTATION_VALIDATION | POST /v2/onboarding-actions/upload-pep-documentation |
FEP_DOCUMENTATION_VALIDATION | POST /v2/onboarding-actions/upload-fep-documentation |
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
ACTIVEstatus. 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
statushas changed toINACTIVEand you need to understand why
Related pages
Updated 4 months ago