Verifícate en tu teléfono. Sin app obligatoria.

• 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,
  "jwt": "",
  "launch_url": "https://www.verihop.com/verify.html?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",
  "requested_claims": ["legalName", "over18"],
  "assurance_required": "basic",
  "deep_link": "verihop://share?session="
}

• 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 botones, QR, emails, SMS, web flows y flujos nativos.
• qr_url: URL segura para QR; actualmente equivalente a launch_url.
• jwt: token de sesión firmado consumido por Verihop. Normalmente los clients partner no lo validan directamente.
• deep_link: campo legacy/native-only de compatibilidad para integraciones con app instalada.

• 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,
  "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, document, passport, residencePermit

legalName, dateOfBirth, over18, over21, documentType, documentNumber, documentExpiry, documentCountry, documentNationality, nationality

Yes. Your backend creates a session using POST /v1/sessions, then renders the returned qr_url inside a QR shown on the desktop page. The user scans that QR with their phone and Verihop opens the best available experience.

Best UX is direct launch: encode the returned qr_url. It is the same universal HTTPS handoff as launch_url and supports app, lightweight, and web fallback paths.

Yes. Verihop uses the same launch_url on both platforms. Your callback shape is also the same: Verihop appends session_id, success-path result_token, and optional callback_jwt.

If you use a custom callback such as ridenow://verified, the Android partner app must declare an intent filter for that scheme and host. If you use an https:// callback for desktop or web-started flows, treat it as a backend endpoint unless your Android app owns that domain with verified App Links.

Use an https:// callback endpoint on your backend. After Verihop completes, your server receives session_id and result_token, then fetches 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.

Callback query parameters are transport metadata only. Verified personal data is intentionally not sent in callback URLs. Your backend must exchange the one-time result_token to fetch the result payload securely. If enabled, callback_jwt can be verified via JWKS for callback authenticity.

Yes, on partner backend when present. Verify signature and claims using Verihop JWKS at GET /.well-known/jwks.json. Validate issuer/audience/expiry and ensure JWT claims match callback query values.

No. Keep API keys server-side and fetch results from your backend only. The frontend/web client should only handle UI and pass state to your backend session.

Create a new session when a session expires or the user abandons the flow. result_token is short-lived and single-use; if consumed or expired, restart with a new POST /v1/sessions.

Provide a fallback page behind your QR flow that can explain how to install/open Verihop and then continue. After install, create a new session and show a fresh QR (do not reuse stale sessions).

POST /v1/sessions supports Idempotency-Key for retry-safe create-session calls: same key + same payload replays the original response, while same key + different payload returns 409 idempotency_key_conflict. Misuse is further mitigated with API-key auth, callback allowlist policy, field allowlist checks, per-customer rate limits/quota, short session TTL, and one-time result_token.