• Una sesión es válida durante 15 minutos desde su creación. Es una única ventana total para abrir el enlace, revisar el documento, revisar y aprobar; no se reinicia después de MRZ, NFC o selfie.
• Cuando la verificación móvil necesita un desafío de seguridad, es válido durante un máximo de 10 minutos, pero nunca más allá de la caducidad de la sesión. iOS y Android usan la misma caducidad emitida por el backend y un margen de seguridad de 15 segundos.
• Cuando pase expires_at, crea una sesión nueva. No reutilices una URL de lanzamiento, código QR ni token de callback caducados.

• app: nombre visible de la app partner dentro de Verihop (máx. 80 caracteres).
• header: título corto de verificación mostrado al usuario (máx. 120 caracteres).
• fields: tokens de campos solicitados; si falta o está vacío, Verihop usa legalName y over18.
• callback: URL base de retorno enviada en POST /v1/sessions. Verihop la abre al terminar y añade session_id, result_token (success path) y opcionalmente callback_jwt; requerida y validada contra tu allowlist de producción.

• Authorization: API key partner en formato bearer.
• Content-Type: usa application/json para parsear el request body.
• Idempotency-Key: clave de retry para dedupe al crear sesiones; envía UUID v4/v7 y reutilízala solo para retries de la misma payload.

{
  "session_id": "sess_123",
  "expires_at": 1730000000,
  "launch_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "app_clip_url": "https://appclip.apple.com/id?p=KycBox.VerifyBox.Clip&session_id=sess_123&token=h_abc123",
  "qr_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "status_url": "https://api.verihop.com/v1/sessions/sess_123"
}

• session_id: identificador único para tracking y obtención del resultado.
• expires_at: expiración de sesión (Unix epoch seconds).
• launch_url: URL principal para web, Android, QR, emails, SMS y handoff general.
• app_clip_url: URL nativa directa del App Clip para apps partner de iOS. Ábrela exactamente como se devuelve; no la reconstruyas.
• qr_url: URL segura para QR; actualmente equivalente a launch_url.
• status_url: endpoint de estado de sesión para polling server-side.

• 401 missing_bearer_token, 401 invalid_api_key
• 403 customer_inactive
• 400 missing_callback_url, invalid_callback_url, callback_host_not_allowed
• 400 field_not_allowed, invalid_field_token, request_too_large
• 409 idempotency_key_conflict, idempotency_key_in_progress
• 429 rate_limit_exceeded, daily_quota_exceeded

{
  "session_id": "sess_123",
  "status": "issued",
  "issued_at": 1730000000,
  "expires_at": 1730000300,
  "last_status": null,
  "last_status_at": null,
  "opened_at": null,
  "result_available": false,
  "result_token_expires_at": null
}

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "kid_2025_01",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

{
  "session_id": "sess_123",
  "status": "success",
  "result": {
    "legalName": "Jane Doe",
    "over18": "yes"
  }
}

• 401 missing_bearer_token, invalid_api_key, missing_result_token
• 403 customer_mismatch, invalid_result_token
• 410 result_token_expired
• 409 result_token_used
• 404 result_not_available, session_not_found

legalName, dateOfBirth, over18, over21, passport, idCard, documentNumber, documentExpiry, documentCountry, documentNationality

El resultado contiene únicamente los campos compatibles solicitados y aprobados por el usuario. Los requisitos de tipo de documento como passport e idCard no incluyen automáticamente todos los atributos del documento.

Sí. Tu backend crea una sesión mediante POST /v1/sessions y muestra la qr_url devuelta dentro de un QR en la página de escritorio. El usuario escanea ese QR con el teléfono y Verihop abre la mejor experiencia disponible.

La mejor experiencia es el inicio directo: codifica la qr_url devuelta. Es el mismo traspaso HTTPS universal que launch_url y admite rutas de app, experiencia ligera y fallback web.

Usa launch_url en Android y para el handoff web general. Una app partner de iOS que quiera mostrar la tarjeta nativa del App Clip debe abrir la app_clip_url devuelta. La forma del callback no cambia: Verihop añade session_id, en caso de éxito result_token y opcionalmente callback_jwt.

Crea la sesión en tu backend y envía la app_clip_url devuelta a tu app iOS. Abre esa URL con SwiftUI Link o UIApplication.open en iOS 17 o posterior. No analices launch_url, no copies su token ni fijes en código el bundle ID del App Clip de Verihop. Si la app completa de Verihop está instalada, iOS la abre conservando la misma sesión.

Si usas un callback personalizado como ridenow://verified, la app Android partner debe declarar un intent filter para ese scheme y host. Si usas un callback https:// para flujos iniciados desde desktop o web, trátalo como un endpoint de backend salvo que tu app Android sea dueña de ese dominio con App Links verificados.

Usa un endpoint de callback https:// en tu backend. Cuando Verihop termina, tu servidor recibe session_id y result_token, y después obtiene GET /v1/sessions/{id}/result server-to-server.

No. Ese token es para Verihop. Los partners deben tratarlo como transporte opaco y usar launch_url para iniciar Verihop.

Los parámetros del callback son solo metadata de transporte. Los datos personales verificados no se envían intencionalmente en callback URLs. Tu backend debe intercambiar el result_token de un solo uso para obtener la payload result de forma segura. Si está habilitado, callback_jwt puede verificarse vía JWKS para autenticar el callback.

Sí, en el backend del partner cuando esté presente. Verifica firma y claims con Verihop JWKS en GET /.well-known/jwks.json. Valida issuer, audience y expiry, y asegúrate de que los claims JWT coincidan con los valores del callback.

No. Mantén las API keys en servidor y obtén resultados solo desde tu backend. El frontend/web client solo debe manejar UI y pasar estado a la sesión de backend.

Crea una nueva sesión cuando una sesión expire o el usuario abandone el flujo. result_token dura poco y es de un solo uso; si se consume o expira, reinicia con un nuevo POST /v1/sessions.

Ofrece una página fallback detrás de tu flujo QR que explique cómo instalar o abrir Verihop y continuar. Después de instalar, crea una nueva sesión y muestra un QR nuevo; no reutilices sesiones caducadas.

POST /v1/sessions soporta Idempotency-Key para llamadas create-session seguras ante retries: la misma key con la misma payload reproduce la respuesta original, mientras que la misma key con una payload distinta devuelve 409 idempotency_key_conflict. El abuso se mitiga además con autenticación por API key, política de callback allowlist, validación de campos permitidos, rate limits/cuota por cliente, TTL corto de sesión y result_token de un solo uso.