Sesiones y estados
Sigue el avance de cada validación de identidad y sabe qué hacer según su resultado.
Introducción
Cada validación de identidad pasa por varias etapas y puede terminar de distintas formas. Si no sabes en qué punto está una validación ni por qué falló, no puedes explicárselo a tu cliente ni ayudarlo a completarla.
En Pomelo, cada validación de KYC o KYB se registra en una sesión, con un estado que te indica en todo momento cómo avanza y, si no se valida, el motivo.
Qué es una sesión
Al iniciar un proceso de KYC (para personas físicas) o de KYB (para compañías), se crea una sesión de validación de identidad. La sesión es la entidad principal de Identity: allí guardamos toda la información de esa verificación.
Con cada sesión:
- Recopilamos todos los datos y documentos necesarios.
- Verificamos la autenticidad de esa información.
- Contrastamos los datos para prevenir actividades ilegales, como el lavado de dinero, la financiación del terrorismo y el fraude.
Un usuario o una compañía pueden tener varias sesiones a lo largo del tiempo, pero solo una sesión en estado temporal a la vez. Cada sesión tiene un código único de referencia; encontrarás un ejemplo en la API de KYC.
Steps de una sesión
Cada sesión tiene varios steps: las etapas de la verificación, cada una con un chequeo distinto. Los steps cambian según si validas a una persona (KYC) o a una compañía (KYB):
| KYC | KYB | |
|---|---|---|
| 1 | Aceptación de TyC (TERMS) | Aceptación de TyC (TERMS) |
| 2 | Prueba de vida (LIVENESS) | Formulario de datos (DATA_ENRICHMENT_MANUAL) |
| 3 | Coincidencia selfie / documento (MATCH_ID) | Validación de empresa (GOVERNMENTAL_CHECK_COMPANY) |
| 4 | OCR (OCR) | Validación de socios (PARTNER_CHECK) |
| 5 | Formulario de datos (DATA_ENRICHMENT_MANUAL) | Validación de documentación (DOCUMENT_CHECK) |
| 6 | Validación de datos (GOVERMENTAL_CHECK_DATA) | Validación de riesgo (EXCLUSION_CHECK) |
| 7 | Validación de foto (GOVERMENTAL_CHECK_SELFIE) | — |
| 8 | Validación de riesgo (EXCLUSION_CHECK) | — |
Encontrarás el detalle de cada step en las guías de KYC y KYB.
Estados de los steps
Cada step tiene su propio estado, y el conjunto de esos estados define el estado de la sesión. Para que la sesión se valide, todos los steps tienen que estar en SUCCESS.
| Estado | Qué significa |
|---|---|
PENDING | Hay información pendiente en el step. |
PROCESSING | Estamos esperando la respuesta de un proveedor. |
SUCCESS | Tu cliente completó el step correctamente. |
FAILED | Tu cliente no completó el step correctamente. |
NOT_AVAILABLE | No podemos acceder a alguno de los servicios que usamos para el step. |
Estados de una sesión
A medida que avanzan los steps, la sesión cambia de estado. Hay dos tipos de estados:
- Temporales: muestran el avance de la sesión.
- Terminales: la sesión terminó y no puede volver a un estado anterior.
| Estado | Tipo | Qué significa |
|---|---|---|
CREATED | Temporal | Se creó la sesión. |
IN_PROGRESS | Temporal | Tu cliente hizo la primera acción en el flujo de validación. |
PROCESSING | Temporal | Esperamos información para hacer verificaciones asincrónicas, o algún proveedor está demorado. Te permite mostrarle a tu cliente un mensaje acorde a la espera. |
MANUAL_REVIEW | Temporal | Al menos un step necesita revisión manual porque no se puede resolver de forma automática. Las sesiones de KYB siempre pasan por revisión manual, para validar la documentación de la compañía. |
VERIFIED | Terminal | Validamos todos los steps de la sesión. |
NOT_VALIDATED | Terminal | No pudimos validar uno o más steps, por lo que no podemos confirmar la identidad. Puedes crear una nueva sesión para el mismo usuario o compañía. |
REJECTED | Terminal | Tras un análisis exhaustivo, la sesión no cumple con los criterios de validación. No se puede crear una nueva sesión para el mismo usuario o compañía. |
EXPIRED | Terminal | Venció el tiempo establecido para acceder al flujo. |
CANCELLED | Terminal | Se creó una nueva sesión para el mismo usuario (tu cliente sigue el flujo en la nueva) o cancelaste la sesión por motivos de seguridad o prevención de fraude. |
Cómo te enteras de cada cambio
Después de crear una sesión, te notificamos cada cambio de estado vía webhook, en el endpoint que configures durante la integración. También puedes consultar la sesión en cualquier momento con la API de KYC.
Sesiones no validadas
Cuando una sesión termina en NOT_VALIDATED, en el Dashboard te mostramos un mensaje de error con el detalle de lo que pasó y el ID de la sesión, para que puedas revisar qué step falló. También puedes obtener el motivo vía API.
Estos son los motivos posibles:
| Motivo | Mensaje de error | Step | Qué pasó |
|---|---|---|---|
ID_ALREADY_VALIDATED | User with specified identification type and value already exists in Users Api | — | Otro usuario ya registró ese documento. |
MISSING_BIRTHDATE | User's birthday is missing and we couldn't determine if is an adult | — | No pudimos corroborar la fecha de nacimiento, así que no podemos confirmar que sea mayor de edad. |
UNDERAGE_USER | User is underage | — | El usuario es menor de edad. |
SELFIE_FAILED | Failed to validate selfie | Prueba de vida | No detectamos la presencia en tiempo real del usuario. Solo ocurre en el flujo web. |
FACE_COULD_NOT_SATISFY_WIDTH | The face does not match the required width | Prueba de vida | El ancho del encuadre del rostro no es correcto. Solo ocurre en el flujo API. |
FACE_COULD_NOT_SATISFY_HEIGHT | The face does not match the required height | Prueba de vida | El alto del encuadre del rostro no es correcto. Solo ocurre en el flujo API. |
PHOTO_HAS_POOR_QUALITY | Photo was taken with low quality | Prueba de vida | La foto es de baja calidad. Solo ocurre en el flujo API. |
PERSON_IS_NOT_LOOKING_STRAIGHT | The person is leaning to one side | Prueba de vida | La persona no miró a la cámara. Solo ocurre en el flujo API. |
NO_PERSON_WAS_DETECTED | No person was detected in the photo | Prueba de vida | No detectamos a ninguna persona en la foto. Solo ocurre en el flujo API. |
PERSON_HAS_FORBIDDEN_ACCESORIES | The person has forbidden accessories | Prueba de vida | La persona tiene accesorios que impiden validar su rostro. Solo ocurre en el flujo API. |
MULTIPLE_FACES_DETECTED | Multiple faces were detected | Prueba de vida | Detectamos más de un rostro en la foto. Solo ocurre en el flujo API. |
ID_MATCH_FAILED | Failed to validate ID | Coincidencia selfie / documento | La foto del documento y el rostro de la prueba de vida coinciden poco: puede que no sea la misma persona o que la foto del documento no sea lo bastante clara. |
ID_NOT_SUPPORTED | ID not supported | Coincidencia selfie / documento | El usuario envió un tipo de documento que no aceptamos. |
DOCUMENT_MISMATCH | Images are not from the same type to analyze | Coincidencia selfie / documento | Las fotos del frente y del dorso no corresponden al mismo documento. |
OCR_CHECK_FAILED | Failed to check OCR | OCR | No pudimos corroborar la información del documento con OCR. |
OCR_CHECK_MISSING | Failed to check OCR | OCR | No identificamos algún dato obligatorio en las imágenes del documento, como el número de documento. |
IS_PEP | The user declared to be PEP | Formulario de datos | Tu cliente declaró ser una persona expuesta políticamente. |
IS_SO | The user declared to be SO | Formulario de datos | Tu cliente declaró ser sujeto obligado. |
DATA_CHECK_FAILED | Failed to validate data in governmental provider | Validación de datos | No pudimos validar con un ente gubernamental los datos obtenidos en el OCR. |
PERSON_NOT_FOUND | Person not found | Validación de datos | No encontramos al usuario en las bases de datos gubernamentales. |
DECEASED_USER | User is declared as deceased | Validación de datos | El ente gubernamental informa que el usuario falleció. |
CPF_IRREGULAR_SITUATION | CPF irregular situation | Validación de datos | El CPF existe, pero está suspendido, cancelado o anulado. |
PARTIAL_NAME | Partial name | Validación de datos | El nombre está incompleto. |
DIVERGENT_NAME | Divergent name | Validación de datos | El nombre no coincide con el de las bases de datos gubernamentales. |
BIRTHDATE_NOT_AVAILABLE | Birthdate not available | Validación de datos | No pudimos validar la fecha de nacimiento en las bases de datos gubernamentales. |
DIVERGENT_BIRTHDATE | Divergent birthdate | Validación de datos | La fecha de nacimiento no coincide con la de las bases de datos gubernamentales. |
EXPIRED_DOCUMENT | Expired document | Validación de datos | El documento está vencido. |
DIVERGENT_NATIONALITY | Divergent nationality | Validación de datos | La nacionalidad informada no coincide con la de las bases de datos gubernamentales. |
DIVERGENT_FISCAL_ID | Divergent fiscal id | Validación de datos | El ID fiscal informado no coincide con el de las bases de datos gubernamentales. |
DIVERGENT_DOCUMENT_ID | Divergent document id | Validación de datos | El número de documento informado no coincide con el de las bases de datos gubernamentales. |
SELFIE_DOESNT_MATCH | User selfie doesn't match with governmental database | Validación de foto | Un ente gubernamental no validó la selfie de la prueba de vida. |
SELFIE_NOT_AVAILABLE | User selfie isn't available in governmental database | Validación de foto | La selfie de la prueba de vida no está en la base de datos del ente gubernamental. |
EXCLUSION_CHECK_FAILED | Failed to validate user in exclusion check | Validación de riesgo | El screening AML (prevención de lavado de activos) dio un resultado positivo para la persona. |
| Motivo | Mensaje de error | Step | Qué pasó |
|---|---|---|---|
CNPJ_INVALID_OR_NOT_COMPLETED | CNPJ is invalid or it is not completed | Validación de empresa | El CNPJ es inválido o está incompleto. |
CNPJ_NOT_REGISTERED | CNPJ is not registered in governmental provider | Validación de empresa | No encontramos el CNPJ en los registros gubernamentales. |
CNPJ_NOT_ACTIVE | CNPJ is not active | Validación de empresa | El CNPJ no está activo. |
UNABLE_TO_VALIDATE_CPF | Unable to validate CPF | Validación de empresa | No pudimos validar el CPF. |
COMPANY_TYPE_INVALID_OR_NOT_COMPLETED | Juridic person is invalid or it is not completed | Validación de empresa | El tipo de compañía es inválido o está incompleto. |
CPF_NOT_MATCH_WITH_CNPJ | CPF does not match with the registered for CNPJ | Validación de empresa | El CPF no coincide con el registrado para ese CNPJ. |
CPF_NOT_LOCATED_IN_CNPJ | CPF is not located in CNPJ | Validación de empresa | El CPF no figura en el CNPJ. |
CPF_NOT_RELATED_WITH_CNPJ | CPF does not related with the CNPJ | Validación de empresa | El CPF no está relacionado con el CNPJ. |
DIFFERENT_JURIDIC_NATURE | Fiscal Id has a different juridic nature | Validación de empresa | El ID fiscal tiene una naturaleza jurídica distinta. |
COMPANY_HAS_COMPANY_AS_PARTNER | A company is not able to have a company as a partner | Validación de empresa | Una compañía no puede tener a otra compañía como socia. |
CPF_VALID_PENDING_REGULAR | Valid CPF with status pending regularization | Validación de empresa | El CPF es válido, pero está pendiente de regularización. |
CPF_VALID_NOT_REGULAR_AND_NOT_PENDING_REGULAR | Valid CPF with status different to regular | Validación de empresa | El CPF es válido, pero su situación no es regular. |
CPF_VALID_UNDERAGE | CPF owner is underage | Validación de empresa | El CPF corresponde a un menor de edad. |
CPF_VALID_DEAD_PERSON | CPF owner is declared as deceased | Validación de empresa | El CPF corresponde a una persona fallecida. |
CPF_VALID_NOT_REGISTERED_ON_FEDERAL_PARTNER | CPF not registered | Validación de empresa | El CPF no existe. |
PARTNER_SESSION_NOT_VALIDATED | A partner session has not been validated | Validación de socios | Todavía no se validó la identidad de uno de los socios. |
PARTNER_SESSION_REJECTED | A partner session has been rejected | Validación de socios | Se rechazó la verificación de identidad de uno de los socios. |
Preguntas frecuentes
¿Puedo volver a validar a alguien si su sesión no se validó?
Depende del estado final. Si la sesión terminó en NOT_VALIDATED, puedes crear una nueva sesión para el mismo usuario o compañía. Si terminó en REJECTED, no.
¿Qué pasa si creo una nueva sesión mientras hay otra en curso?
La sesión anterior pasa a CANCELLED y tu cliente sigue el flujo en la nueva, porque solo puede haber una sesión en estado temporal a la vez.
¿Por qué una sesión de KYB siempre pasa por MANUAL_REVIEW?
Porque nuestro equipo revisa manualmente la documentación de cada compañía.