Checkify
Documentos del desarrollador

Verifique en su backend

Después de que se complete la inserción del navegador, su servidor debe verificar el resultado con una clave API del sitio antes de permitir el registro, el pago o cualquier acción protegida.

Verificación del servidor en 5 minutos.

  1. Agregue el código Checkify para navegador a su página.
  2. El elemento incrustado inicia la sesión Checkify y escribe la referencia de verificación en su formulario.
  3. Tu sistema backend lee el valor del campo oculto.
  4. Tu backend envía ese valor a POST /v1/qr/results/verify como request_id.
  5. Si se aprueban las reclamaciones requeridas, se autorizará la acción protegida.
  6. Nunca confíes únicamente en el estado del frontend.

El campo de formulario oculto puede llamarse checkify_token, pero su valor es el request_id Checkify.

Flujo de extremo a extremo

1. Cree una clave API de sitio

En el panel de su empresa, abra Desarrollador y cree una clave API de sitio para el sitio que está integrando. Guárdelo únicamente en las variables de entorno del servidor; nunca lo envíe al navegador.

¿Utilizando el frontend SDK?

No es necesario llamar manualmente a GET /v1/qr/pass/{PASS_ID}/start. El elemento incrustado Checkify JavaScript inicia la sesión, recibe el request_id y lo escribe en su formulario automáticamente.

Tu backend solo necesita:

2. Reciba el request_id en su servidor.

El frontend SDK escribe el request_id Checkify en un campo de formulario oculto después de que el usuario complete la verificación. El nombre de campo predeterminado es checkify_token; ese es el nombre del campo, no un tipo de token independiente. Envíe el valor del campo al endpoint de verificación como request_id.

La transferencia de la aplicación móvil puede devolver checkify_request_id en la URL de la página. SDK lo lee al cargar la página; su servidor sigue verificando el mismo valor de request_id.

Formulario POST desde tu frontend

{
  "email": "user@example.com",
  "checkify_token": "56a57761-ff5b-42f0-9c97-6c13e223e017"
}

Verifica la solicitud desde tu backend.

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "required_fields": [],
  "consume": true
}

Integración manual del frontend únicamente

3. Pruebas manuales con cURL

Los desarrolladores de backend normalmente no llaman a /start. Utilice esta sección solo cuando cree un frontend personalizado o realice pruebas sin la incrustación. En zsh/bash, entrecomille las URL para que ? no se trate como un comodín.

Se requiere el encabezado Origin para /start

Pass Start solo funciona desde un dominio web registrado. Los navegadores envían el origen automáticamente; cURL no. Envíe el origen (o X-Checkify-Site-Url) con un nombre de host que aparezca en Sitios → dominios permitidos. El nombre de host debe coincidir exactamente: checkify.me y www.checkify.me son diferentes.

Problema de prueba más común

Si /start devuelve HTTP 403, su ID de contraseña aún podría ser válido. La causa habitual es que el dominio de la solicitud no esté incluido en la lista de dominios permitidos, o que www.example.com esté registrado pero se haya utilizado example.com (o viceversa).

Utilice un sitio de prueba dedicado y pase su panel de control Checkify para realizar pruebas de integración. Las claves del sitio API utilizan el prefijo csk_; no existe un formato de clave de prueba independiente. No realice pruebas con el proceso de producción hasta que haya confirmado los flujos de éxito y denegación.

# Step A — start a session (replace PASS_ID and YOUR_REGISTERED_DOMAIN)
curl -sS \
  -H "Accept: application/json" \
  -H "Origin: https://YOUR_REGISTERED_DOMAIN" \
  "https://checkify.me/v1/qr/pass/chk_live_YOUR_PASS_ID/start?request_type=human"

# Response includes request_id and qr_url — open qr_url and complete verification

# Step B — verify on your server (after the user completes verification)
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "PASTE_request_id_FROM_STEP_A",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Utilice su clave API del sitio únicamente en la llamada de verificación. Complete la verificación en la aplicación antes de llamar a la función de verificación; de lo contrario, recibirá el estado "pendiente".

Reclamaciones requeridas por caso de uso

Configure required_claims para que coincida con la prueba que requiere su acción protegida. Los nombres de las reclamaciones deben coincidir con los que Checkify aprobó para esa sesión de verificación. Las comprobaciones de edad utilizan age_over_{N} (por ejemplo, age_over_18). Se admiten umbrales dinámicos de 10 a 110 cuando la solicitud integrada utiliza el tipo de solicitud correspondiente.

Caso de uso Reclamaciones requeridas sugeridas Notas
Bot / Reemplazo de CAPTCHA ["human_verified"] Confirma que un usuario real completó el flujo Checkify.
Contenido para mayores de 13 años o productos orientados al público juvenil. ["age_over_13"] Úselo cuando su pase solicite age_over_13.
Contenido para mayores de 16 años o normas regionales de edad ["age_over_16"] Úselo cuando su pase solicite age_over_16.
Vapeo, alcohol o pago para mayores de 18 años ["age_over_18"] Adapta el rango de edad a tu producto y mercado.
Productos restringidos para mayores de 21 años (cuando corresponda) ["age_over_21"] Úselo cuando su pase solicite age_over_21.
Política de venta minorista Challenge 25 o más estricta ["age_over_25"] Úselo cuando su pase solicite age_over_25.
umbral de edad personalizado ["age_over_N"] Utilice age_over_N, donde N es de 10 a 110, en consonancia con el tipo de solicitud de inserción.

Incrustar tipo de solicitud → reclamación del servidor

El tipo de solicitud del navegador debe coincidir con la declaración que usted verifica en el servidor.

Tipo de solicitud de inserciónreclamaciones requeridas
human["human_verified"]
age_over_13["age_over_13"]
age_over_16["age_over_16"]
age_over_18["age_over_18"]
age_over_21["age_over_21"]
age_over_25["age_over_25"]
age_over_N["age_over_N"] (N = 10–110)

campos obligatorios opcionales

Además de required_claims, puede exigir campos de identidad aprobados concretos (por ejemplo país o franja de edad) cuando su integración los haya recogido. Pase los nombres en required_fields; si faltan en el resultado aprobado, verify devuelve missing_required_fields con missing_fields en error.details.

4. Realiza la verificación en tu servidor.

Llama a POST /v1/qr/results/verify con la clave API de tu sitio antes de otorgar acceso. Trata la referencia del navegador (request_id o token de sondeo heredado) como no confiable hasta que Checkify confirme el resultado.

POST https://checkify.me/v1/qr/results/verify
Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "consume": true
}

También puedes enviar token en lugar de request_id. La clave API está limitada a su sitio Checkify; no debe enviar site_id en el cuerpo de la solicitud.

Ejemplos de implementación

# checkify_token from your form POST is sent as request_id
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Cuándo usar consumir

Utilice consume: true para acciones protegidas finales. — pago, registro, restablecimiento de contraseña, compra con restricción de edad, acceso a contenido protegido

Use consumir: false solo para — Pruebas, depuración o comprobaciones no definitivas cuyo resultado debe verificarse posteriormente.

Para acciones reguladas o de alto riesgo, se recomienda usar consume: true para que el mismo resultado de verificación no pueda reutilizarse para múltiples decisiones protegidas.

Fallo cerrado por acciones reguladas

Si su sistema backend no puede acceder a Checkify, no permita el pago con restricción de edad, el acceso a juegos de azar, el acceso a contenido para adultos, la compra de cigarrillos electrónicos o alcohol, u otras acciones protegidas sin un resultado confirmado del servidor.

Utilice tiempos de espera HTTP cortos (por ejemplo, 10 segundos). Reintente una o dos veces en caso de errores transitorios 5xx o de red, y luego deniegue el acceso. Registre los incidentes en el servidor y muestre mensajes seguros para el usuario. No exponga los detalles internos del error Checkify a los clientes.

try {
  const verdict = await verifyCheckifyResult(requestId);

  if (!verdict.allow) {
    return res.status(403).json({ error: "Verification required" });
  }

  // Continue protected action
} catch (err) {
  console.error("Checkify verification unavailable", err);

  return res.status(403).json({
    error: "Verification is temporarily unavailable. Please try again.",
  });
}

Servidores SDK y herramientas

The Checkify monorepo includes @checkify/server (Node.js) and checkify-server (Python) packages for server-side verify calls. There is no published OpenAPI spec or Postman collection yet — use the examples on this page and POST /v1/qr/results/verify directly.

@checkify/server v1.0.0 está publicado en npm. El paquete Python checkify-server se incluye en el monorepo Checkify SDK.

Ventana de caducidad del resultado

Las verificaciones completadas caducan después de QR_RESULT_MAX_AGE_SECONDS (valor predeterminado: 900 segundos / 15 minutos). Tras la caducidad, verify devuelve result_expired; solicite al usuario que vuelva a verificar.

Puntos finales de sondeo de estado (interfaces personalizadas)

Los parámetros JavaScript y SDK gestionan el estado de la sesión para las incrustaciones estándar. Úselos únicamente cuando cree una interfaz personalizada que llame manualmente a GET /v1/qr/pass/{pass_id}/start.

Manejo de respuestas

En caso de éxito, Checkify devuelve HTTP 200 con success: true y status: completed. Permita el acceso solo cuando se cumplan los requisitos (por ejemplo, human_verified: true).

{
  "success": true,
  "status": "completed",
  "message": "Verification result confirmed",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "site_id": "YOUR_SITE_ID",
  "business_id": "YOUR_BUSINESS_ID",
  "approved_claims": {
    "human_verified": true
  },
  "approved_fields": [],
  "signed_result": {
    "payload": { "...": "..." },
    "signature": "...",
    "signature_algorithm": "EdDSA",
    "key_id": "checkify:default"
  }
}

Resultado firmado

El objeto signed_result permite a su backend conservar un registro de auditoría a prueba de manipulación de que Checkify aprobó el claim requerido en el momento de la verificación. La mayoría de integraciones solo necesitan approved_claims. Negocios regulados o de alto riesgo también pueden almacenar signed_result. proof_metadata anidado puede incluir evidencia criptográfica u operativa (por ejemplo metadatos de assurance, tipos de evidencia o hashes de consentimiento), no documentos de identidad ni fecha de nacimiento en bruto. No trate los campos de assurance anidados como certificación ni garantía de confianza; revise certification_status y su propia política. No almacene más información personal de la necesaria.

Si el cliente aún no ha finalizado en la aplicación, Checkify devuelve HTTP 200 con success: false y status: pending. Se deniegan las acciones protegidas y se solicita al usuario que complete la verificación.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
CampoSignificado
successtrue cuando se completa la verificación y requisitos coincidente
statuscompleted o pending
approved_claimsReclamaciones Checkify aprobadas, p.e. human_verified: true
signed_resultCarga útil firmada opcional para pistas de auditoría

Cargas útiles de error JSON

Cuando no se puede realizar la verificación, Checkify devuelve un código HTTP 4xx/5xx con un cuerpo estructurado JSON. Compruebe el código de error y registre los detalles del error en el servidor. Devuelva mensajes genéricos a los usuarios finales.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
Código HTTP Significado Acción recomendada
missing_authorization401No se envió ningún encabezado de autorización.Enviar autorización: Bearer YOUR_SITE_API_KEY solo desde el código del servidor.
invalid_token401Falta el token de portador, está mal formado o no es una clave API de sitio válida.Verifique la clave en el panel de control de su empresa y guárdela en las variables de entorno.
expired_token401La clave del sitio API ha sido revocada.Crea una nueva clave de sitio API y rótala en tus servidores.
missing_required_field400 / 422El request_id o token no aparece en el cuerpo de JSON.Pasa el request_id del campo oculto de tu formulario, o el token de sondeo si tu integración aún lo utiliza.
invalid_request_id400La referencia no se pudo analizar o está vacía después de la normalización.Asegúrese de que su interfaz de usuario envíe el request_id Checkify sin cambios.
result_not_found404No existe ninguna solicitud de verificación para esa referencia.Rechazar la acción. Es posible que el usuario haya manipulado el campo oculto o enviado una sesión antigua.
result_expired410La verificación se completó hace demasiado tiempo como para confiar en ella para esta acción.Pídele al usuario que vuelva a escanear y que llame a verify con el nuevo request_id.
verification_failed403 / 409Desajuste de sitio/negocio, resultado ya consumido (HTTP 409) o un fallo genérico de verificación.Deniegue el acceso. Inspeccione error.details. Para huecos de claims/campos, vea missing_required_claims y missing_required_fields.
missing_required_claims403developers_server.err_missing_required_claims_meaningdevelopers_server.err_missing_required_claims_action
missing_required_fields403developers_server.err_missing_required_fields_meaningdevelopers_server.err_missing_required_fields_action
unknown_required_attributes400developers_server.err_unknown_required_attributes_meaningdevelopers_server.err_unknown_required_attributes_action
business_not_operational403La cuenta comercial está bloqueada, archivada o no está operativa.Comuníquese con el propietario del negocio o con el soporte de Checkify. No permita acciones protegidas hasta que la cuenta esté activa.
validation_errors422El cuerpo JSON no superó la validación del esquema (HTTP 422).Inspeccione error.details.validation_errors para detectar mensajes a nivel de campo. Corrija los tipos request_id, required_claims o required_fields antes de volver a intentarlo.
rate_limited429Demasiadas llamadas de verificación en un corto período de tiempo.Reintentar con retroceso exponencial. Verificar solo en acciones protegidas, no en cada visualización de página.
server_error500+Checkify no pudo completar la verificación debido a un problema temporal del servidor.Inténtalo de nuevo una o dos veces, luego cierra la sesión si falla y registra el incidente.

Webhooks y verificación asíncrona

Actualmente, la verificación del servidor es síncrona: el backend verifica el request_id cuando el usuario envía la acción protegida. Para los flujos de pago, registro y control de acceso, este es el enfoque recomendado. No se requieren webhooks de verificación de propósito general para las integraciones estándar. GoHighLevel y otras integraciones de socios pueden usar una configuración de webhook saliente independiente en el panel de control empresarial.

Errores comunes

Recordatorio de seguridad

Trate el campo oculto como una referencia no confiable, no como una prueba. Verifique siempre con la clave API de su sitio en el servidor antes de otorgar acceso. Usar consume: true para acciones únicas como registrarse o restablecer contraseña.

Próximos pasos