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.
ESTADOS TEMPORALESEN VALIDACIÓNESTADOS TERMINALESPRIMERAACCIÓNESPERANDOPROVEEDORRESULTADODIVERGENTECREATEDIN_PROGRESSPROCESSINGMANUAL_REVIEWVERIFIEDValidado y correctoREJECTEDValidado pero rechazadoNOT_VALIDATEDAlguna etapa no se validóEXPIREDVenció el tiempoCANCELLEDNueva sesión o cancelación
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.

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.

Pomelo AI

Asistente de inteligencia artificial para consultas sobre la API de Pomelo
¡Hola!¿Cómo puedo ayudarte hoy?
Sesiones y estados