Documentation API
Trois appels pour intégrer la vérification, plus les webhooks pour savoir comment elle s'est passée.
Authentification
Chaque requête porte la clé dans l'en-tête Authorization. Vous créez les clés depuis le tableau de bord, section Clés API, et vous ne les voyez en clair qu'une seule fois.
Authorization: Bearer kyc_live_xxxxxxxxxxxxxxxxxxxxxLe flux
- 1. Ouvrez un dossier (
POST /verifications). Cela ne coûte rien et n'expire pas. - 2. Générez le lien (
POST /verifications/{id}/attempts) et envoyez-le à la personne comme vous le souhaitez. - 3. La personne ouvre le lien : consentement, document, liveness. Rien à installer.
- 4. Vous recevez
verification.submitted: la personne a terminé. Si vous avez activé l'approbation automatique et que le dossier est au vert sur tous les contrôles, l'approbation suit immédiatement ; sinon, une personne tranche — votre équipe depuis le tableau de bord, ou l'un de nos opérateurs avec l'offre Institutionnelle. - 5. Vous recevez
verification.approved,.declinedou.retry_required.
Endpoints
/api/v1/verificationsOuvre un dossier. Ne génère aucun lien et ne coûte rien.
REQUÊTE
{ "external_ref": "cliente-4821", "declared_name": "Mario Rossi", "return_url": "https://app.esempio.it/firma/abc" }RÉPONSE
{ "id": "…", "status": "created", "livemode": true, "created_at": "…" }/api/v1/verifications/{id}/attemptsGénère le lien. À usage unique, avec expiration. Une nouvelle tentative invalide la précédente.
REQUÊTE
{ "instruction": "Fotografa il documento disteso, senza riflessi." }RÉPONSE
{ "id": "…", "url": "https://…/v/<token>", "expires_at": "…", "livemode": true }/api/v1/verifications/{id}Statut, résultat et qui tranche le dossier, avec les données lues sur le document quand il y en a.
RÉPONSE
{ "id": "…", "status": "approved", "record": { "surname": "…", "verifiedFields": […] } }Webhooks
Vous configurez l'endpoint depuis les Paramètres. En live, il doit être en https.
Le corps
Il ne contient jamais de données personnelles. Seulement des identifiants : les données, vous les lisez vous-même avec GET /verifications/{id}, en vous authentifiant.
{
"id": "285a4274-a751-4a24-9479-12100bf9d313",
"type": "verification.approved",
"created": 1787037080,
"livemode": true,
"data": {
"verification_id": "01a013b5-dc12-7ab2-a8c5-f00f0bab35bc",
"status": "approved",
"external_ref": "cliente-4821"
}
}Vérifier la signature
L'en-tête X-KYCJET-Signature vaut t=<timestamp>,v1=<hmac>. Le HMAC est un SHA-256 sur "<timestamp>.<corps brut>" avec votre secret de signature. Comparez en temps constant et rejetez les horodatages trop anciens.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verifica(rawBody, header, secret) {
const [t, v1] = header.split(',').map(p => p.split('=')[1])
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
const atteso = createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex')
return timingSafeEqual(Buffer.from(atteso), Buffer.from(v1))
}Livraison et nouvelles tentatives
Répondez 2xx dès que vous avez pris l'événement en charge. Toute autre réponse, ou un silence de plus de 10 secondes, déclenche une nouvelle tentative : backoff exponentiel de 30 secondes jusqu'à 6 heures, 12 tentatives sur une quinzaine d'heures environ, puis la livraison est abandonnée.
La livraison est au moins une fois : le même événement peut vous parvenir deux fois. Utilisez id comme clé d'idempotence — il reste identique même quand nous remettons une livraison en file à la main.
Erreurs
Chaque erreur a la même forme : { "code": …, "message": …, "details"?: … }. Faites le switch sur code, jamais sur le message. Le message arrive en italien, en anglais ou en français selon Accept-Language ; le code, lui, ne change pas.
- 401 UNAUTHORIZED
- Clé absente, erronée ou révoquée. Les trois réponses sont identiques à dessein.
- 402 INSUFFICIENT_CREDITS
- Solde insuffisant (le code a gardé son ancien nom par compatibilité) : si votre solde ne couvre pas le coût maximal d'une vérification, le POST qui génère le lien ne le génère pas. Cela arrive avant d'impliquer quelqu'un, pas après.
- 404 VERIFICATION_NOT_FOUND
- Le dossier n'existe pas, ou n'appartient pas à votre organisation. Là aussi, même réponse.
- 409 VERIFICATION_NOT_RETRYABLE
- Vous avez demandé une nouvelle tentative sur un dossier déjà tranché. Ce code EST la politique de nouvelle tentative.
- 422 DOCUMENT_REJECTED
- La photo est inutilisable. Aucun débit, le lien reste valide : la personne reprend la photo.
- 503 CHECKS_UNAVAILABLE
- Nos contrôles ne répondent pas. C'est de notre faute : les photos sont bonnes, le lien reste valide, aucun débit. La personne réessaie dans quelques minutes.