KYC JAAK para API

En este apartado explicaremos cómo hacer una implementación de KYC JAAK para API. Antes de comenzar es necesario haber consultado la sección KYC JAAK ya que será necesario contar con un Short Key.

Requisitos

Todas las llamadas API que realizaremos a continuación será mediante la arquitectura REST (Representational State Transfer), con el estándar web HTTP (HyperText Transfer Protocol) y firmando la comunicación con el formato JSON (JavaScript Object Notation).
Recomendamos tener un conocimiento por lo menos básico de estos 3 conceptos para poder continuar con esta guía.

Intercambio de Short Key por Token de Sesión de KYC

Un Short Key es un identificador único de una Sesión KYC. Para poder realizar llamadas a los Servicios JAAK que forman parte de una Sesión KYC, es fundamental autenticarse y autorizar dichas llamadas conociendo el origen de la sesión. Para ello, se utiliza un Token de Sesión KYC, el cual podemos obtener a partir del Short Key.

Para obtener un Token de Sesión KYC a partir de un Short Key debemos hacer la siguiente llamada API:

URL

POST https://sandbox.api.jaak.ai/api/v1/kyc/session

Header

Short-Key: String
Origin-Device String

Request

{}

Response

{
  "accessToken": String,
  "step": Integer,
  "sessionId": String,
  "assets": {
    "document": null | String,
    "liveness": null | String,
  },
  "document": String
}

Objeto assets

Todas las siguientes llamadas API deben ser autenticadas mediante una cabecera denominada "Authorization", cuyo valor debe ser "Bearer token-sesion-kyc".
El cual puedes obtenerlo del la propiedad accessToken.

Una vez hecho el intercambio del Short Key y obtenido el Token de Sesión KYC, ya podemos hacer uso de los Servicios JAAK asignados para realizar un proceso KYC.

Servicios JAAK

El proceso KYC JAAK para API requiere de una serie de servicios esenciales, diseñados para verificar la identidad de una persona de manera detallada. Cada uno de los Servicios JAAK mencionado a continuación desempeña un papel fundamental para garantizar que el proceso sea seguro, preciso y cumpla con las normativas legales.

• Geolocalización
• Verificación de documento
• Extracción de datos del documento
• Verificación de datos en lista negra
• Verificación de vida
• Verificación de la titularidad del documento

Todos los servicios proporcionados por JAAK son vitales para fortalecer la seguridad del proceso KYC y garantizar su fiabilidad. Además, aseguran el cumplimiento de las normativas internacionales, protegiendo la identidad y los documentos de los clientes durante todo el proceso.

A continuación se detallan cada uno de estos servicios:

1. Geolocalización

El servicio de Geolocalización de JAAK se utiliza para registrar la ubicación (latitud y longitud) donde se lleva a cabo la Sesión KYC. Es importante tener en cuenta que la ubicación es recolectada desde el dispositivo que utiliza el usuario final para realizar la Sesión KYC.

Realiza la siguiente llamada API para registrar la ubicación del dispositivo en la Sesión KYC.

URL

POST https://sandbox.api.jaak.ai/api/v1/kyc/session/location

Header

Authorization: Bearer token-session-kyc

Request

{ 
    "latitude": Double,
    "longitude": Double
}

Response

{}

El servicio de Geolocalización no tiene un impacto directo en los resultados finales de la sesión, pero es una herramienta útil para la recopilación de datos y en algunos casos, como el financiero, necesaria para llevar a cabo sus procesos.

Continuemos con el siguiente paso...

2. Verificación de documento

La etapa de verificación de documento tiene como objetivo principal validar la autenticidad de los documentos presentados por el usuario, como identificaciones oficiales y así prevenir el fraude con documentos falsos, alterados o que no corresponden a un documento legítimo.

En algunas ocasiones existen documentos que tienen anverso y reverso, de ahí dependerá si se captura una o dos imágenes por documento para usar este servicio, estas imágenes de dichos documentos deben ser convertidas a Base64 antes de ser enviadas al servicio. Por lo tanto, es fundamental realizar el proceso de codificación de imagen para asegurar su correcta transmisión y procesamiento.

Realiza la siguiente llamada API enviando las imágenes o imagen del documento.

URL

POST https://sandbox.api.jaak.ai/api/v3/document/verify

Header

Authorization: Bearer token-session-kyc

Request

{
    "imageFront": String,
    "imageBack": String,
    "dataVerification": Boolean
}

Response

{
    "eventId": String,
    "requestId": String,
    "evaluation": String,
    "document": {
        "type": String,
        "side": String,
        "country": String,
        "icaoCode": String
    },
    "state": {
        "documentCompleteSides": Boolean,
        "dataConsistent": Boolean,
        "documentLiveness": Boolean,
        "securityFeatures": Boolean,
        "documentValidity": Boolean,
        "imageQuality": Boolean,
        "handPresence": Boolean,
        "message": String,
        "validations": {
            "namesMatch": Boolean,
            "lastNameMatch": Boolean,
            "birthDateMatch": Boolean,
            "personalIdNumberMatch": Boolean,
            "message": String
        },
        "photoForgery": Boolean
    },
    "processTime": Integer
}

Objeto document

Objeto state

Objeto state.validations

El objeto state, ubicado dentro del Response, muestra el estado de verificación del documento a lo largo del proceso de validación. Este objeto incluye un grupo de propiedades que indican si el documento cumple o no con los requisitos de autenticidad, calidad y consistencia.

JAAK recomienda que todas las propiedades de verificación se completen con éxito para una mayor seguridad, aunque esto no es obligatorio por lo tanto puedes seleccionar solo un conjunto de propiedades según sus necesidades. Algunos ejemplos incluyen:

• Aceptar la verificación si todas las validaciones son exitosas.
• Solicitar una nueva captura si la calidad de la imagen es baja o faltan elementos claves.
• Rechazar la verificación si se detectan manipulaciones o inconsistencias graves en los datos.

Cada propiedad dentro de state juega un papel específico en la verificación del documento y pueden ser usadas para tomar decisiones y ser integradas en su sistema de verificación.

La propiedad dataVerification dentro de Request, cuando se establece como true, proporciona validaciones adicionales sobre los datos de los documentos mexicanos. Estas validaciones, que se encuentran en state.validations de Response, se realizan exclusivamente para documentos mexicanos a través de entidades oficiales como RENAPO. Para identificaciones de otras nacionalidades, todas las validaciones serán false debido a la incompatibilidad del servicio con estos documentos.

Después de verificar y validar el documento, se puede proceder a la extracción de datos en el siguiente paso, es importante recordar que las mismas imagenes enviadas en este paso se usaran en el siguiente para buscar tener la mayor coherencia en la Sesión KYC.

3. Extracción de datos del documento

El objetivo de la extracción de datos, es capturar y organizar la información del documento para facilitar su análisis y almacenamiento. Esta información se utilizará posteriormente en los siguientes pasos como la verificación de la titularidad del documento y la búsqueda de datos en listas negras.

Para asegurar la coherencia y eficiencia del proceso, es esencial que uses las mismas imágenes del documento tanto en el paso de verificación del documento como en este paso. Recuerda que la codificación de la imagen a Base64 es crucial antes de enviarlas al servicio para garantizar su correcta transmisión y procesamiento.

Realiza la siguiente llamada API enviando las imágenes o imagen del documento.

URL

POST https://sandbox.api.jaak.ai/api/v4/document/extract

Header

Authorization: Bearer token-session-kyc

Request

{
  "imageFront": String,
  "imageBack": String,
  "documentSessionSelected": {
    "country": String
  }
}

Response

{
    "eventId": String,
    "requestId": String,
    "status": String,
 		"processingTime": String,
     "state": {
        "message": String,
        "documentCompleteSides": Boolean
    },
    "content": {
        "data": {
            "personal": {
                "firstName": String,
                "secondName": String,
                "surname": String,
                "motherSurname": String,
                "fullName": String,
                "sex": String,
                "dateOfBirth": String,
                "face": String,
                "placeOfBirth": String,
                "nationality": String,
                "maritalStatus": String,
                "extra": {
                    "ocr": String,
                    "registerYear": String,
                    "rfc": String
                }
            },
            "address": {
                "fullAddress": String,
                "postalCode": String,
                "extra": {
                    "street": String,
                    "externalNumber": String,
                    "internalNumber": String,
                    "neighborhood": String,
                    "city": String,
                    "state": String
                }
            },
            "document": {
                "type": String,
                "side": String,
                "country": {
                    "name": String,
                    "isoAlpha3Code": String,
                    "isoAlpha2Code": String,
                    "icaoCode": String
                },
                "number": String,
                "personalIdNumber": String,
                "additionalNumber": String,
                "dateOfIssue": String,
                "expiration": {
                    "date": String,
                    "isPermanent": Boolean
                },
                "issuingAuthority": String,
                "extra": {}
            }
        }
    }
}

Objeto state

Objeto content

Objeto content.data

Objeto content.data.personal

Objeto content.data.address

Objeto content.data.document

Objeto content.data.document.country

Objeto content.data.document.expiration

El objeto state, ubicado dentro del Response, muestra el estado de la extracción del documento. Este objeto incluye un grupo de propiedades que indican si el documento cumple o no con los requisitos de la extracción.

JAAK recomienda que todas las propiedades de extracción se completen con éxito para una mayor seguridad, aunque esto no es obligatorio por lo tanto puedes seleccionar solo un conjunto de propiedades según sus necesidades. Algunos ejemplos incluyen:

• Pedir la captura del lado faltante o contraparte del documento en caso de ser requerido.
• Solicitar una nueva captura si existe un error dentro la extracción de los datos del documento.

De los datos extraídos del documento en esta etapa, hay algunos que serán utilizados en los siguientes pasos del proceso. En la sección Verificación en listas negras los datos que se necesitan son:

Verificación del servicio INE en listas negras

• content.data.document.additionalNumber (CIC)
• content.data.personal.extra.ocr (OCR)

Verificación del servicio INTERPOL en listas negras

• content.data.personal.name
• content.data.personal.secondName
• content.data.personal.sureName
• content.data.personal.motherSurname

Verificación del servicio OFAC en listas negras

• content.data.personal.name
• content.data.personal.secondName
• content.data.personal.sureName
• content.data.personal.motherSurname

Verificación del servicio RENAPO en listas negras

• content.data.document.personalIdNumber (CURP)

Verificación del servicio SAT en listas negras

• content.data.personal.name
• content.data.personal.secondName
• content.data.personal.sureName
• content.data.personal.motherSurname
• content.data.personal.extra.rfc

En la sección Verificación de la titularidad del documento, el dato necesario obtenido de esta extracción es:

• content.data.personal.face

Una vez extraídos e identificados los datos del documento los utilizaremos en los siguientes pasos.

4. Verificación de datos en listas negras

Una vez extraídos los datos del documento en el paso anterior, procedemos a verificar esta información contra diversos servicios de listas negras como: Interpol y OFAC. Este paso es crucial para asegurar que el cliente no esté relacionado con actividades ilícitas ni vinculado a personas o entidades de alto riesgo. A su vez, hay información que sí deben ser encontrados en otras listas, que no necesariamente son catalogadas como listas negras, como: INE, RENAPO y SAT.

Los servicios de listas negras a los que se tiene acceso en este paso son: INE, Interpol, OFAC, RENAPO y SAT.

En esta etapa, puedes buscar en diferentes servicios de listas negras, pero solo uno a la vez. Cada servicio requiere información específica. La firma para usar estos servicios es la misma para todos, pero los datos que debes enviar varían según la lista que consultes. Después de la explicación de la URL y sus parámetros que se muestra a continuación, encontrarás una serie de tablas que aclaran qué campos debes enviar por servicio y cómo relacionarlos con la información obtenida en el paso anterior.

URL

POST https://sandbox.api.jaak.ai/api/v2/blacklist/investigate

Header

Authorization: Bearer token-session-kyc

Request

{
    "services": {
        "ine": Boolean,
        "interpol": Boolean,
        "ofac": Boolean,
        "renapo": {
            "curp": Boolean
        },
        "sat": {
            "sat69b": Boolean
        },
        "cdc": {
            "rccFico": Boolean
        }
    },
    "payload": {
        "person": {
            "name": String,
            "secondName": String,
            "lastName": String,
            "secondLastName": String,
            "birthDate": String,
            "nationality": String,
            "additionalLastName": String
        },
        "address": {
            "address": String,
            "neighborhood": String,
            "municipality": String,
            "city": String,
            "state": String,
            "postalCode": String
        },
        "identifications": {
            "curp": String,
            "rfc": String,
            "socialSecurityNumber": String,
            "electorKey": String,
            "ine": {
                "cic": String,
                "ocr": String
            }
        },
        "extras": {
            "commonId": String,
            "wantedIn": String
        }
    }
}

Objeto services

Objeto payload

Objeto payload.person

Objeto payload.address

Objeto payload.identifications

Objeto payload.identifications.ine

Objeto payload.extras

Response

{
    "eventId": String,
    "responseId": String,
    "processTime": Double,
    "organization": String,
    "service": String,
    "result": {},
    "state": {
        "foundInService": Bolean,
        "mustBeFound": Boolean,
        "message": String
    }
}

Objeto state

A continuación, se exhibirán una serie de tablas organizadas por servicio de listas. En estas tablas, se detallarán los campos necesarios para cada lista y su correspondencia con los datos extraídos del paso anterior.

Para hacer la verificación mediante el servicio INE deberás enviar los siguientes datos:

Para hacer la verificación mediante el servicio INTERPOL deberás enviar los siguientes datos:

Para hacer la verificación mediante el servicio OFAC deberás enviar los siguientes datos:

Para hacer la verificación mediante el servicio RENAPO deberás enviar los siguientes datos:

Para hacer la verificación mediante el servicio SAT deberás enviar los siguientes datos:

A continuación, te mostraremos un ejemplo de una consulta al servicio de RENAPO

Request

{
    "services": {
        "ine": false,
        "interpool": false,
        "ofac": false,
        "renapo": {
            "curp": true
        },
        "sat": {
            "sat69b": false
        },
        "cdc": {
            "rccFico": false
        }
    },
    "payload": {
        "identifications": {
            "curp": "aqui va la curp"
        }
    }
}

Response

{
    "eventId": "749f88b9-ecce-4f4c-920a-f8ece706501a",
    "responseId": "",
    "processTime": 0.23123526573181152,
    "organization": "curp",
    "service": "validaCurp",
    "result": null,
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": false,
        "mustBeFound": true
    }
}

Como se muestra en el ejemplo anterior, se realizó una consulta al servicio de RENAPO. En la solicitud, podemos observar que solo se activó un servicio, services.renapo.curp, y que únicamente se enviaron los campos necesarios para llevar a cabo la búsqueda de dicho servicio.

El campo state dentro del Response debería haber indicado que se encontró a una persona para que la búsqueda se considere exitosa. Sin embargo, el campo foundInService muestra que no se encontró a la persona.

En resumen, al contrastar los datos extraídos del documento con diversas listas negras, garantizamos la protección tanto de la empresa como de los usuarios. Este proceso asegura la integridad y el cumplimiento del sistema, ayudando a prevenir fraudes.

Una vez verificado los datos del documento en las listas negras continuemos con los siguientes pasos.

5. Verificación de vida

El objetivo de la verificación de vida o liveness es garantizar que la persona que está realizando el proceso de verificación de identidad es un ser humano real y no una imagen, un video o un intento de fraude. Esta etapa se realiza para prevenir el uso de fotografías o videos falsificados y proteger la integridad del proceso KYC.

Durante esta etapa, se lleva a cabo una validación biométrica para confirmar que la persona que está interactuando con el sistema es realmente quien dice ser. Utilizando tecnologías avanzadas de detección facial, esta verificación asegura que solo personas reales puedan completar el proceso de identificación.

Para utilizar este paso, se requiere un video de 5 segundos con el rostro de la persona a validar. Es esencial que la persona no lleve accesorios y que el video tenga buena iluminación.

Este video debe ser convertido a Base64 antes de ser enviado al servicio. Por lo tanto, es fundamental realizar el proceso de codificación de video para asegurar su correcta transmisión y procesamiento.

Realiza la siguiente llamada API para realizar el proceso de verificación de vida.

URL

POST https://sandbox.api.jaak.ai/api/v1/liveness/verify-and-bestframe

Header

Authorization: Bearer token-session-kyc

Request

{
  "video": String
}

Response

{
    "eventId": String,
    "requestId": String,
    "processTime": String,
    "score": Double,
    "bestFrame": String,
    "state": {
        "isRealPerson": Boolean,
        "message": String
    }
}

Objeto state

El valor true de la propiedad state.isRealPerson, dentro del Response de la llamada de prueba de vida, confirma que la verificación fue exitosa y no hubo ningún ataque.

Además, la misma respuesta nos devuelve una propiedad llamada bestFrame, que se utiliza para obtener el mejor fotograma del video, es decir, en el que aparece la persona con mejor posición, iluminación, etc. Este fotograma se utilizará en el siguiente paso.

6. Verificación de la titularidad del documento

La etapa final requiere una comparación entre dos imágenes para verificar que la persona que realiza el proceso KYC es la titular del documento. Se comparará la imagen del obtenida (bestFrame) durante el paso de verificación de vida con la imagen del rostro extraída del documento (content.data.personal.face) durante el paso de extracción de datos.

Así como en pasos anteriores, las imágenes deben estar en Base64 antes de ser enviadas al servicio. Por lo tanto, es fundamental realizar la verificación de las imagenes para asegurar su correcta transmisión y procesamiento.

URL

POST https://sandbox.api.jaak.ai/api/v2/oto/verify

Request

{
    "eventId": String,
    "image1": String,
    "image2": String
}

Response

{
    "eventId": String,
    "requestId": String,
    "score": Double,
    "distance": Double,
    "process_time": Integer,
    "metadata": {
        "image1": {
            "accessories": {
                "glass": Boolean,
                "sunGlass": Boolean,
                "hat": Boolean,
                "mask": Boolean
            },
            "image_quality": {
                "isCorrectBrightness": Boolean,
                "isCorrectBlur": Boolean,
                "isCorrectHeight": Boolean,
                "isCorrectWidth": Boolean,
                "isCorrectResolution": Boolean,
                "isCorrectVerticalRotation": Boolean,
                "isCorrectHorizontalRotation": Boolean,
                "isCorrectRotation": Boolean,
                "isCorrectSizeFace": Boolean,
                "isCorrectNumberFaces": Boolean
            }
        },
        "image2": {
            "accessories": {
                "glass": Boolean,
                "sunGlass": Boolean,
                "hat": Boolean,
                "mask": Boolean
            },
            "image_quality": {
                "isCorrectBrightness": Boolean,
                "isCorrectBlur": Boolean,
                "isCorrectHeight": Boolean,
                "isCorrectWidth": Boolean,
                "isCorrectResolution": Boolean,
                "isCorrectVerticalRotation": Boolean,
                "isCorrectHorizontalRotation": Boolean,
                "isCorrectRotation": Boolean,
                "isCorrectSizeFace": Boolean,
                "isCorrectNumberFaces": Boolean
            }
        }
    },
    "codes": null,
    "state": {
        "rejectedBadQuality": Boolean,
        "rejectedAccessories": Boolean,
        "isSamePerson": Boolean,
        "message": String
    }
}

Objeto state

La propiedad state.isSamePerson nos permite asegurar que la persona que se está identificando en la verificación de vida sea la misma que la del documento proporcionado.

En resumen, si la propiedad state.isSamePerson es aceptada, entonces podemos considerar que la verificación de la titularidad del documento ha sido exitoso.

Es importante que finalices las sesiones KYC. Te explicaremos cómo hacerlo en el siguiente paso.

Finalización de la Sesión KYC

Una vez ejecutados los Servicios JAAK, se debe finalizar la Sesión KYC de manera adecuada mediante la API, esto garantiza la seguridad y un correcto funcionamiento del KYC JAAK.

El proceso de finalización se lleva a cabo mediante una llamada a la siguiente URL. Es esencial incluir el Token de Sesión KYC para informar la Sesión KYC que queremos finalizar.

URL

POST https://sandbox.api.jaak.ai/api/v1/kyc/session/finish

Header

Authorization: Bearer token-session-kyc

Request

{}

Response

{}

El estado HTTP 200 confirma que una sesión KYC se ha finalizado con éxito. Cualquier otro código de estado HTTP recibido de la llamada indicaría un error.

¡Excelente!

Si has llegado hasta aquí, ya tienes todo el conocimiento necesario para implementar correctamente un KYC JAAK.

Para poder ver el estado de tus sesiones y visualizarlas, continua con la guía en KYC JAAK donde te explicamos cómo hacerlo.