Documentation Développeur

Intégrez la vérification d'identité SAGAPASS - le seul service exposé aux partenaires pour le moment.

Introduction

SAGAPASS capture lui-même (sur sa propre page web, caméra en direct) la pièce d'identité et le selfie de votre utilisateur, effectue l'OCR, la vivacité et la correspondance visage↔pièce, puis vous notifie le résultat par webhook. Vous n'avez jamais besoin de manipuler de photos vous-même.

C'est aujourd'hui le seul service exposé via l'API partenaire. D'autres services (identification entreprise, etc.) sont en préparation - contactez-nous si votre besoin dépasse la vérification d'identité.

Identifiants

Après approbation de votre demande de partenariat, vous recevez depuis votre tableau de bord :

client_id / client_secret - authentification HTTP Basic sur les appels sortants.
webhook_secret - vérifie la signature des webhooks entrants. Distinct du client_secret.

Créer une session de vérification

POST https://sagapass.com/api/partner/v1/verification-sessions
Auth: Basic (client_id, client_secret)
Body (JSON):
  document_type: "national_id" | "passport" | "drivers_license"
  partner_reference: string
  webhook_url: string
  partner_submitted_data: object

Réponse (201):
  session_token: string
  capture_url: string
  expires_at: string (ISO 8601)

Redirigez l'utilisateur vers capture_url - SagaPass gère toute la capture caméra (pièce + selfie + vivacité active) sur sa propre page.

Vérifier le statut (filet de sécurité)

GET https://sagapass.com/api/partner/v1/verification-sessions/{session_token}/status
Auth: Basic (client_id, client_secret)

À utiliser uniquement si le webhook tarde - le webhook reste le chemin principal, pas du polling actif.

Webhook de résultat

SagaPass envoie le résultat en POST sur votre webhook_url.

Header X-Saga-Signature, valeur sha256=<hmac>.
Calcul : hash_hmac('sha256', <corps brut>, webhook_secret) - comparez en temps constant (hash_equals).
Événements : verification.completed, verification.failed, verification.expired, kyc.expired.
Le payload contient session_token et/ou kyc_id - utilisez-les comme clé d'idempotence.

Répondez vite (200 {"received": true}) et traitez le résultat en file d'attente, jamais en synchrone dans le contrôleur du webhook.

Champs disponibles selon le type de pièce

Tous les types renvoient au minimum document_number, full_name, date_of_birth, date_of_expiry.

Type	Champs supplémentaires
`national_id`	`sex`, `place_of_birth`, `date_of_issue`
`passport`	`sex`, `nationality`, `personal_number`, `mrz_line1`, `mrz_line2`
`drivers_license`	`sex`, `nif`, `address`, `blood_type`, `license_category`, `place_of_issue`, `date_of_issue`

Ne bloquez pas votre décision sur face_match_score seul - c'est un signal indicatif, pas un verdict.

Pièce expirée

Une pièce dont date_of_expiry est dans le passé est automatiquement rejetée (verification.failed) - vous n'avez rien à vérifier vous-même.

Revérifier un KYC ID durable

GET https://sagapass.com/api/partner/v1/kyc-identities/{kyc_id}/status
Auth: Basic (client_id, client_secret)

Permet de vérifier qu'une identité déjà validée est toujours dans sa période de validité, sans repasser par toute la capture.

Aller plus loin : le centre de documentation partenaire couvre en détail chaque guide, y compris les cas particuliers déjà rencontrés en production.