Espace développeurs · Documentation API
API VeriChap KYCendpoints, authentification, erreurs & bonnes pratiques.
L'API VeriChap KYC permet de piloter vos vérifications depuis vos propres systèmes : création de dossiers, récupération des décisions, gestion des webhooks, exports pour vos outils de reporting et de conformité.
Pour démarrer rapidement
- 1. Créez une clé API dans la console VeriChap.
- 2. Configurez votre environnement (sandbox / production).
- 3. Appelez l'endpoint de création de vérification.
- 4. Écoutez le webhook de décision pour mettre à jour vos systèmes.
Les exemples ci-dessous utilisent des valeurs génériques. Vous les adapterez avec vos propres identifiants, référentiels clients et modèles de données internes.
Authentification & en-têtes HTTP
L'authentification se fait via une clé secrète (secret key) envoyée dans l'en-tête Authorization: Bearer. Utilisez des clés différentes pour la sandbox et la production, stockées dans un coffre-fort de secrets.
Exemple en cURL
curl https://api.verichap-kyc.com/v1/verifications \
-H "Authorization: Bearer sk_sandbox_..." \
-H "Content-Type: application/json" \
-d '{
"reference": "CLIENT-12345",
"type": "identity_check",
"country": "CI",
"channel": "mobile_app"
}'Bonnes pratiques de sécurité
- • Ne jamais exposer vos secret keys côté front.
- • Restreindre les IP autorisées si nécessaire.
- • Mettre en place une rotation régulière des clés.
- • Monitorer les appels suspects (pics, géos inattendues).
Endpoints principaux
Vous trouverez ci-dessous un aperçu des principaux endpoints. La documentation complète détaillera l'ensemble des paramètres et schémas de réponses.
POST /v1/verifications
Crée une nouvelle vérification (identité, biométrie, screening, etc.) pour un client donné. Retourne un identifiant unique à utiliser côté front & back-office.
- • reference (string) : ID interne de votre client.
- • type (string) : identity_check, screening, etc.
- • country (string) : code pays ISO.
GET /v1/verifications/:id
Récupère l'état courant d'une vérification, y compris les décisions, scores de risque et journaux associés.
- • Statut global (PENDING, APPROVED, DECLINED, REVIEW).
- • Détails par module (doc, biométrie, screening...).
- • Liens vers les pièces jointes et traces d'audit.
GET /v1/verifications?reference=...
Liste paginée de toutes les vérifications liées à un même client, utile pour vos écrans "historique KYC".
GET /v1/audit-events
Permet d'interroger les journaux d'audit globaux (décisions, accès, exports, etc.) pour vos outils internes.
Exemple backend Node.js (création & suivi d'une vérification)
Exemple minimaliste utilisant un client Node.js pour créer une vérification et en récupérer ensuite le résultat.
import { createClient } from "@verichap-kyc/node";
const client = createClient({
secretKey: process.env.VERICHAP_SECRET_KEY!,
environment: process.env.VERICHAP_ENVIRONMENT || "sandbox",
});
export async function runKycFlow() {
// 1) Créer une vérification
const verification = await client.verifications.create({
reference: "CLIENT-12345",
type: "identity_check",
country: "CI",
channel: "mobile_app",
});
console.log("Verification created:", verification.id);
// 2) Récupérer la décision ultérieurement
const result = await client.verifications.retrieve(verification.id);
console.log("Verification status:", result.status);
}Points d'attention
- • Toujours valider l'origine des données clients (KYC initial).
- • Loguer l'ID de vérification dans vos bases internes.
- • Ne pas bloquer vos threads sur des appels réseau longs.
- • Préférer les webhooks aux polls intensifs dès que possible.
Modèle d'erreurs & limitations de débit
Les erreurs API suivent une structure standardisée, avec un code machine, un message lisible et éventuellement un champ details pour les informations complémentaires.
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "invalid_request",
"message": "Champ 'country' manquant ou invalide.",
"details": {
"field": "country"
}
}
}Rate limiting & résilience
- • Les appels sont soumis à des quotas par minute & par jour.
- • En cas de dépassement, un code 429 est renvoyé.
- • Implémentez un backoff exponentiel côté client.
- • Surveillez les en-têtes de limites dans vos dashboards.
Aller plus loin avec l'écosystème développeurs VeriChap
La documentation API s'utilise en complément des SDKs front, des environnements sandbox et des outils de logs & monitoring.