Umbrales de biometría (V3)

Solo disponible en V3

Durante la verificación comparamos el rostro de la credencial con la selfie del usuario y revisamos que la persona esté realmente frente a la cámara (prueba de vida). Cada comprobación da un porcentaje, y la sesión la aprueba solo si ese porcentaje alcanza un umbral: el porcentaje mínimo de aceptación.

Al crear la sesión puedes fijar tus propios umbrales para que la verificación sea más estricta o más flexible según tu caso de uso. Si no envías ninguno, se aplican los valores por defecto.

Nota

Los umbrales son opcionales y no tienen costo adicional. Se fijan por sesión, así que puedes usar valores distintos en cada una (por ejemplo, más estrictos para operaciones de mayor monto).

Umbrales disponibles

Parámetro	Qué compara	Rango permitido	Por defecto	Aprueba cuando
face_match_threshold	El rostro de la credencial contra la selfie.	70 a 100	90	La similitud es mayor o igual al umbral.
liveness_threshold	La confianza de la prueba de vida.	50 a menos de 100	80	La confianza es mayor al umbral.
qr_face_match_threshold	La fotografía del QR del reverso contra el rostro de la credencial. Solo aplica si la sesión se creó con qr_validation: true.	70 a 100	80	La similitud es mayor o igual al umbral.

Todos son porcentajes y aceptan decimales, por ejemplo 87.5.

La prueba de vida no acepta 100

La prueba de vida aprueba solo cuando la confianza es mayor que el umbral. Con 100 ninguna persona podría pasarla, por eso el valor debe ser menor a 100 (por ejemplo, 99.9).

Cómo configurarlos

Envía los umbrales en el cuerpo de la solicitud al crear la sesión. Puedes mandar uno, dos o los tres: los que omitas toman su valor por defecto.

JSON

{
    "validations": ["INE", "CURP"],
    "face_match_threshold": 92,
    "liveness_threshold": 85
}

Con validación de QR

{
    "validations": ["INE", "CURP"],
    "qr_validation": true,
    "face_match_threshold": 92,
    "liveness_threshold": 85,
    "qr_face_match_threshold": 85
}

cURL

curl -X POST https://api.verificamex.com/identity/v3/identity/sessions \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": ["INE", "CURP"],
    "face_match_threshold": 92,
    "liveness_threshold": 85
  }'

Consejo

qr_face_match_threshold solo tiene efecto si también envías qr_validation: true. Ver Validación de QR.

Cómo saber qué umbrales se aplicaron

La respuesta de creación confirma los umbrales de la sesión en la raíz del objeto, incluidos los que tomaron su valor por defecto:

{
    "uuid": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
    "status": "OPEN",
    "verification_url": "https://kyc.verificamex.com/verify/870c7eee-3604-4995-aa98-bc8fa6aa1112?t=...",
    "liveness_threshold": 85,
    "face_match_threshold": 92,
    "qr_face_match_threshold": 80,
    "result": null
}

El detalle de la sesión y el webhook los incluyen en el objeto thresholds, junto a coincidence (la similitud facial que obtuvo el usuario). Así puedes ver contra qué valor se calificó cada sesión:

{
    "data": {
        "id": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
        "status": "FINISHED",
        "result": 100,
        "coincidence": 95.1,
        "thresholds": {
            "liveness": 85,
            "face_match": 92,
            "qr_face_match": 80
        }
    }
}

Campo	Tipo	Descripción
thresholds.face_match	Number	Umbral de comparación facial con el que se calificó la sesión. Siempre trae un valor.
thresholds.liveness	Number o null	Umbral de la prueba de vida: el que enviaste o el valor por defecto (80).
thresholds.qr_face_match	Number o null	Umbral de la fotografía del QR: el que enviaste o el valor por defecto (80).

Bajo el umbral, coincidence llega en 0

Si la similitud facial no alcanza face_match_threshold, coincidence llega en 0: el servicio de comparación facial no informa la similitud de los rostros que quedan por debajo del umbral. Un 0 junto al error FACE-MATCH-KYC-001 significa “menor que el umbral”, no “similitud de 0%”. Lo mismo aplica a qr_validation.face_match.confidence con qr_face_match_threshold.

Nota

Las sesiones creadas antes de que existiera esta opción muestran face_match: 90 y null en los otros dos: son los valores por defecto con que se calificaron.

Cómo afectan el resultado de la sesión

Si una comprobación no alcanza su umbral, se agrega una entrada al arreglo errors y el result de la sesión pasa a 0, sin importar que Lista Nominal o RENAPO hayan pasado.

Key	Se agrega cuando
FACE-MATCH-KYC-001	La similitud entre la credencial y la selfie es menor que face_match_threshold.
LIVENESS-KYC-001	La prueba de vida no se completó, o su confianza no superó liveness_threshold.
QR-KYC-003	La fotografía del QR no alcanzó qr_face_match_threshold. Solo cuando el QR se leyó con éxito: ver Cómo afecta el resultado.

La entrada de FACE-MATCH-KYC-001 indica en Output el umbral con que se comparó. La similitud llega en 0 porque, como se explica arriba, no se informa cuando queda por debajo del umbral:

{
    "Key": "FACE-MATCH-KYC-001",
    "Name": "Comprobación facial",
    "Category": "KycBiometryValidation",
    "Result": false,
    "Output": "face_match_confidence=0; umbral=92",
    "Message": "La comprobación facial de kyc.verificamex.com no alcanzó el umbral requerido"
}

Por ejemplo, con face_match_threshold: 92:

1. Similitud de 95.1: aprueba la comparación facial y coincidence es 95.1.
2. Similitud de 92: aprueba, porque es igual al umbral, y coincidence es 92.
3. Similitud menor que 92: coincidence llega en 0, se agrega FACE-MATCH-KYC-001 a errors y el result pasa a 0.

Cómo elegir tus umbrales

• Subir un umbral hace la verificación más estricta: baja el riesgo de suplantación, pero rechaza a más personas legítimas, por ejemplo cuando la foto de la credencial es antigua, hay poca luz o la cámara es de baja calidad.
• Bajar un umbral reduce los rechazos, pero aumenta el riesgo de aprobar a alguien que no es el titular de la credencial.

Te recomendamos empezar con los valores por defecto, revisar cuántas sesiones se rechazan con FACE-MATCH-KYC-001 o LIVENESS-KYC-001 y qué coincidence obtienen las aprobadas, y ajustar en pasos pequeños.

Bajar el umbral de rostro aumenta el riesgo

El valor por defecto de face_match_threshold es 90. Si lo bajas, se aprobarán sesiones que con el valor por defecto se rechazan. Hazlo solo si tu proceso tiene otros controles para confirmar la identidad del usuario.

Errores de validación

Si un umbral está fuera de su rango o no es un número, la sesión no se crea y recibes un 422 que indica el campo con el problema:

{
    "message": "face_match_threshold debe ser de al menos 70.",
    "errors": {
        "face_match_threshold": [
            "face_match_threshold debe ser de al menos 70."
        ]
    }
}

Valor enviado	Mensaje
face_match_threshold o qr_face_match_threshold menor que 70	… debe ser de al menos 70.
face_match_threshold o qr_face_match_threshold mayor que 100	… no puede ser mayor que 100.
liveness_threshold menor que 50	liveness_threshold debe ser de al menos 50.
liveness_threshold de 100 o más	liveness_threshold debe ser menor que 100.
Un valor que no es número	… debe ser un número.

Diferencia con la V2

Los umbrales no son configurables en las sesiones creadas con la V2.

Por sesión

Cada sesión puede llevar sus propios umbrales.

Sin costo adicional

Configurarlos no consume tokens extra.

Rostro: 90 por defecto

Si no envías nada, se mantiene el criterio de siempre.

Visibles en la respuesta

El detalle y el webhook indican contra qué valor se calificó.