API BloKYC — Documentation d'intégration

📚 Overview

L'API BloKYC permet aux développeurs d'intégrer la vérification d'identité biométrique dans leurs applications via une API REST simple et sécurisée.

Version actuelle

v1

URL de base

https://blokyc.me/api/v1

Format des données

JSON

🚀 Démarrage rapide

Suivez ces étapes pour intégrer BloKYC en quelques minutes :

1

Obtenez une clé API

Connectez-vous à votre compte BloKYC, allez dans Paramètres > API, puis cliquez sur "Nouvelle clé". La clé sera affichée une seule fois — conservez-la précieusement.

Format des clés API :

bky_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2

Soumettez les documents

Envoyez les documents d'identité et les données personnelles via l'endpoint POST /kyc/sessions.

✨

Alternative : Hosted KYC (recommandé)

Au lieu d'envoyer un payload complet (données + fichiers), vous pouvez demander une session hosted. BloKYC vous retourne une URL sécurisée à ouvrir côté utilisateur final, qui complète la vérification directement sur BloKYC.me (formulaire, upload, liveness).

Exemple (cURL)

curl -X POST https://blokyc.me/api/v1/kyc/sessions \
  -H "X-API-Key: bky_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "hosted",
    "redirect_url": "https://client.com/return",
    "callback_url": "https://client.com/webhook/kyc",
    "country_iso3": "BEN",
    "document_type": "passport",
    "first_name": "DOHETO JAMAL DEEN",
    "last_name": "FASSINOU"
  }'

Réponse : le champ hosted_url est retourné dans data.

3

Démarrez la vérification biométrique

Créez une session liveness et récupérez l'URL du challenge à afficher à votre utilisateur.

4

Recevez les résultats

Poll le statut ou configurez des webhooks pour recevoir les notifications en temps réel.

✨ Hosted KYC

Le mode hosted permet de générer une URL BloKYC.me sécurisée au lieu d'envoyer un payload complet (données + fichiers). L'utilisateur final complète la vérification directement sur BloKYC.me (formulaire, upload, liveness).

1) Créer une session hosted

curl -X POST https://blokyc.me/api/v1/kyc/sessions \
  -H "X-API-Key: bky_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "hosted",
    "redirect_url": "https://client.com/return",
    "callback_url": "https://client.com/webhook/kyc",
    "country_iso3": "BEN",
    "document_type": "passport",
    "first_name": "DOHETO JAMAL DEEN",
    "last_name": "FASSINOU"
  }'

Le champ hosted_url est retourné dans la réponse.

2) Rediriger l'utilisateur final

Ouvrez hosted_url dans un navigateur (webview ou navigateur système).

Une fois terminé, vous recevez les résultats via webhooks et/ou callback_url, et l'utilisateur peut être renvoyé vers redirect_url.

Le traitement (OCR, liveness, décisions) reste identique au mode standard.

🔑 Authentification

Toutes les requêtes API (sauf health check) doivent inclure votre clé API dans le header HTTP X-API-Key.

curl -H "X-API-Key: bky_abc123def456..." \
     -H "X-Client-ID: 550e8400-e29b-41d4-a716-446655440000" \
     https://blokyc.me/api/v1/kyc/sessions

Header optionnel X-Client-ID

Incluez le client_uuid de votre application dans le header X-Client-ID pour un suivi précis des requêtes par appareil/application. Ce UUID est généré automatiquement lors de votre inscription et est disponible dans votre profil.

Gardez votre clé API confidentielle

Ne la communiquez jamais publiquement et ne la stockez jamais dans votre code frontend. Utilisez toujours votre serveur backend.

🔌 Endpoints

GET /api/v1/health — Public, pas d'authentification

Retourne le statut de santé du service.

Response (200 OK)

{
  "status": "healthy",
  "version": "1.0.0",
  "checks": {
    "database": "ok",
    "kyc_service": "ok"
  },
  "timestamp": "2026-05-20T17:00:00Z"
}

POST /api/v1/kyc/sessions

Créer une nouvelle session KYC.

Mode Hosted (sans fichiers)

Envoyez mode=hosted (JSON) pour recevoir une URL BloKYC.me sécurisée à partager à votre utilisateur. Le reste du pipeline (OCR, liveness, webhooks/callback) reste identique.

Payload (application/json)

{
  "mode": "hosted",
  "callback_url": "https://client.com/webhook/kyc",
  "redirect_url": "https://client.com/return",
  "country_iso3": "BEN",
  "document_type": "passport",
  "first_name": "DOHETO JAMAL DEEN",
  "last_name": "FASSINOU",
  "date_of_birth": "1984-07-19",
  "document_number": "B0778827",
  "document_expiry": "2027-01-19"
}

Response (201 Created)

{
  "data": {
    "id": "115",
    "reference": "KYC-2026-000115",
    "status": "pending",
    "hosted_url": "https://blokyc.me/verify/hky_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "hosted_expires_at": "2026-05-20T17:00:00Z"
  }
}

Payload (multipart/form-data)

Champ	Type	Description	Requis
document_type	string	passport, id_card, drivers_license	✓
document_front	file	Image recto (jpg, jpeg, png, pdf, max 5 Mo)	✓
document_back	file	Image verso (requis si id_card/drivers_license)	—
first_name	string	Prénom(s) en MAJUSCULES	✓
last_name	string	Nom en MAJUSCULES	✓
date_of_birth	string	YYYY-MM-DD	✓
document_number	string	Numéro du document en MAJUSCULES	✓
document_expiry	string	YYYY-MM-DD	✓
country_iso3	string	Code pays ISO3 (ex: BEN, FRA, USA)	✓
callback_url	string	URL de callback personnalisée	—

Exemple de payload

{
  "document_type": "passport",
  "first_name": "DOHETO JAMAL DEEN",
  "last_name": "FASSINOU",
  "date_of_birth": "1984-07-19",
  "document_number": "B0778827",
  "document_expiry": "2027-01-19",
  "country_iso3": "BEN",
  "callback_url": "https://client.com/webhook/kyc"
}
// + file : document_front (binary)
// + file : document_back (optionnel)

Response (201 Created)

{
  "data": {
    "id": "115",
    "reference": "KYC-2026-000115",
    "status": "pending",
    "document_type": "passport",
    "document_number": "B0778827",
    "country": "BEN",
    "personal": {
      "first_name": "DOHETO JAMAL DEEN",
      "last_name": "FASSINOU",
      "date_of_birth": "1984-07-19",
      "document_number": "B0778827",
      "document_expiry": "2027-01-19",
      "country_iso3": "BEN"
    },
    "created_at": "2026-05-20T16:10:00Z",
    "updated_at": "2026-05-20T16:10:00Z"
  }
}

GET /api/v1/kyc/sessions — ?page=1&per_page=20&status=pending

Lister toutes les sessions du tenant (pagination incluse).

Response (200 OK)

{
  "data": [
    {
      "id": "115",
      "reference": "KYC-2026-000115",
      "status": "approved",
      "document_type": "passport",
      "confidence_score": 85.5,
      "created_at": "2026-05-20T16:10:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 85
  }
}

GET /api/v1/kyc/sessions/{id}

Récupérer les détails d'une session spécifique.

Response (200 OK)

{
  "data": {
    "id": "115",
    "reference": "KYC-2026-000115",
    "status": "approved",
    "document_type": "passport",
    "document_number": "B0778827",
    "country": "BEN",
    "confidence_score": 85.5,
    "personal": {
      "first_name": "DOHETO JAMAL DEEN",
      "last_name": "FASSINOU",
      "date_of_birth": "1984-07-19"
    },
    "ocr_result": {
      "decision": "VERIFIED",
      "cross_check": [
        {
          "field": "first_name",
          "status": "MATCH",
          "form_value": "DOHETO JAMAL DEEN",
          "doc_value": "DOHETO JAMAL DEEN"
        }
      ],
      "flags": []
    },
    "liveness": {
      "passed": true,
      "face_match_score": 85.5,
      "face_match_decision": "APPROVED"
    },
    "created_at": "2026-05-20T16:10:00Z",
    "updated_at": "2026-05-20T16:15:00Z",
    "verified_at": "2026-05-20T16:15:00Z"
  }
}

GET /api/v1/kyc/sessions/{id}/documents/{type} — type : front | back | selfie

Télécharger un document (front, back, selfie). Retourne l'image binaire.

Response (200 OK)

Content-Type: image/jpeg
Content-Disposition: attachment; filename="front_115.jpg"

Vérification Biométrique (Liveness)

POST /api/v1/kyc/sessions/{id}/liveness

Créer une session liveness pour une session KYC existante.

Payload (JSON)

{
  "callback_url": "https://client.com/webhook/liveness"
}

Response (201 Created)

{
  "data": {
    "token": "abc123def456...",
    "liveness_url": "https://blokyc.me/liveness/abc123def456...",
    "status": "pending",
    "expires_at": "2026-05-20T17:00:00Z"
  }
}

GET /api/v1/liveness/{token}/status

Polling du statut d'une session liveness.

Response (200 OK)

{
  "data": {
    "token": "abc123def456...",
    "liveness_url": "https://blokyc.me/liveness/abc123def456...",
    "status": "completed",
    "liveness_passed": true,
    "face_match_score": 85.5,
    "face_match_decision": "APPROVED",
    "expires_at": "2026-05-20T17:00:00Z",
    "completed_at": "2026-05-20T16:55:00Z"
  },
  "done": true,
  "message": "Vérification biométrique réussie."
}

Gestion API

GET /api/v1/keys

Lister toutes vos clés API.

POST /api/v1/keys

Créer une nouvelle clé API.

Payload (JSON)

{
  "name": "Production App",
  "callback_url": "https://myapp.com/api/kyc/callback",
  "scopes": ["kyc:read", "kyc:write", "liveness:read", "liveness:write"],
  "rate_limit": 60
}

PUT /api/v1/keys/{id}

Modifier une clé API (nom, callback_url, scopes, rate_limit).

Payload (JSON)

{
  "callback_url": "https://new-url.com/callback",
  "name": "Updated Name"
}

DELETE /api/v1/keys/{id}

Révoquer une clé API.

POST /api/v1/webhooks

Enregistrer une URL de webhook pour recevoir les notifications.

Payload (JSON)

{
  "url": "https://client.com/webhook/kyc",
  "events": [
    "kyc.session.approved",
    "kyc.session.rejected",
    "kyc.liveness.completed"
  ]
}

Response (201 Created)

{
  "data": {
    "id": "1",
    "url": "https://client.com/webhook/kyc",
    "events": ["kyc.session.approved", "kyc.session.rejected"],
    "secret": "whsec_abc123def456...",
    "created_at": "2026-05-20T16:00:00Z"
  }
}

🔔 Webhooks & Callbacks

BloKYC offre deux methodes pour recevoir les resultats en temps reel : le callback URL (simple) et les webhooks (avance).

URL de Callback (recommande)

Chaque cle API peut avoir une URL de callback. BloKYC envoie automatiquement les evenements KYC a cette URL. Les payloads incluent desormais toujours le bloc personal (si disponible) afin de permettre a l'integrateur de mettre a jour les informations utilisateur (nom, prenom, pays, etc.).

Comment configurer :

1. Allez dans Parametres > API

2. Creez une cle API avec votre URL de callback, ou cliquez sur "+ Callback" sur une cle existante

3. BloKYC enverra les resultats automatiquement a votre URL

Payload envoye (POST JSON) :

{
  "event": "kyc.session.approved",
  "session_id": "115",
  "reference": "KYC-2026-000115",
  "status": "approved",
  "personal": {
    "first_name": "DOHETO JAMAL DEEN",
    "last_name": "FASSINOU",
    "date_of_birth": "1984-07-19",
    "document_number": "B0778827",
    "document_expiry": "2027-01-19",
    "country_iso3": "BEN",
    "document_type": "passport"
  },
  "confidence_score": 85.5,
  "verified_at": "2026-05-20T16:15:00Z",
  "timestamp": "2026-05-20T16:15:00Z"
}

Ou via l'API :

curl -X POST https://blokyc.me/api/v1/keys \
  -H "X-API-Key: bky_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "callback_url": "https://myapp.com/api/kyc/callback"}'

Webhooks (avance)

Les webhooks permettent de choisir precisement quels evenements recevoir et de verifier l'authenticite avec une signature HMAC-SHA256.

Informations personnelles dans les payloads

Tous les evenements KYC envoyés via webhooks incluent un champ personal (si disponible), contenant les informations saisies par l'utilisateur et/ou collectees pendant la verification.

Evenements disponibles

kyc.session.created — Nouvelle session créée

kyc.ocr.completed — Analyse document terminée

kyc.liveness.completed — Vérification biométrique terminée

kyc.session.approved — Vérification approuvée

kyc.session.rejected — Vérification rejetée

Signature de sécurité

Chaque webhook est signé avec HMAC-SHA256 via le header X-BloKYC-Signature. Utilisez votre webhook secret pour vérifier l'intégrité du payload.

$signature = hash_hmac('sha256', $payloadJson, $webhookSecret);
if ($signature === $receivedSignature) {
    // Payload authentique
}

💻 Exemples de code

Créer une session KYC :

curl -X POST https://blokyc.me/api/v1/kyc/sessions \
  -H "X-API-Key: bky_abc123def456..." \
  -H "X-Client-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: multipart/form-data" \
  -F "document_type=passport" \
  -F "first_name=DOHETO JAMAL DEEN" \
  -F "last_name=FASSINOU" \
  -F "date_of_birth=1984-07-19" \
  -F "document_number=B0778827" \
  -F "document_expiry=2027-01-19" \
  -F "country_iso3=BEN" \
  -F "document_front=@front.jpg"

Créer une session KYC avec Guzzle :

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://blokyc.me/api/v1/',
    'headers' => [
        'X-API-Key'    => 'bky_abc123def456...',
        'X-Client-ID'  => '550e8400-e29b-41d4-a716-446655440000',
    ],
]);

$response = $client->post('kyc/sessions', [
    'multipart' => [
        ['name' => 'document_type', 'contents' => 'passport'],
        ['name' => 'first_name', 'contents' => 'DOHETO JAMAL DEEN'],
        ['name' => 'last_name', 'contents' => 'FASSINOU'],
        ['name' => 'date_of_birth', 'contents' => '1984-07-19'],
        ['name' => 'document_number', 'contents' => 'B0778827'],
        ['name' => 'document_expiry', 'contents' => '2027-01-19'],
        ['name' => 'country_iso3', 'contents' => 'BEN'],
        ['name' => 'document_front', 'contents' => fopen('front.jpg', 'r')],
    ],
]);

$session = json_decode($response->getBody(), true);

Créer une session KYC avec fetch :

const formData = new FormData();
formData.append('document_type', 'passport');
formData.append('first_name', 'DOHETO JAMAL DEEN');
formData.append('last_name', 'FASSINOU');
formData.append('date_of_birth', '1984-07-19');
formData.append('document_number', 'B0778827');
formData.append('document_expiry', '2027-01-19');
formData.append('country_iso3', 'BEN');
formData.append('document_front', frontFile);

const response = await fetch('https://blokyc.me/api/v1/kyc/sessions', {
    method: 'POST',
    headers: {
        'X-API-Key': 'bky_abc123def456...',
        'X-Client-ID': '550e8400-e29b-41d4-a716-446655440000',
    },
    body: formData,
});

const session = await response.json();

Créer une session KYC avec requests :

import requests

headers = {
    'X-API-Key': 'bky_abc123def456...',
    'X-Client-ID': '550e8400-e29b-41d4-a716-446655440000',
}
files = {'document_front': open('front.jpg', 'rb')}
data = {
    'document_type': 'passport',
    'first_name': 'DOHETO JAMAL DEEN',
    'last_name': 'FASSINOU',
    'date_of_birth': '1984-07-19',
    'document_number': 'B0778827',
    'document_expiry': '2027-01-19',
    'country_iso3': 'BEN',
}

response = requests.post(
    'https://blokyc.me/api/v1/kyc/sessions',
    headers=headers,
    files=files,
    data=data
)
session = response.json()

⚠️ Gestion des erreurs

401 missing_api_key

Header X-API-Key absent.

401 invalid_api_key

Clé API invalide ou révoquée.

422 validation_error

Erreurs de validation dans les données soumises.

429 rate_limit_exceeded

Trop de requêtes. Limite de 60 req/min par clé API.

API BloKYC Documentation

📚 Overview

🚀 Démarrage rapide

Obtenez une clé API

Soumettez les documents

Alternative : Hosted KYC (recommandé)

Démarrez la vérification biométrique

Recevez les résultats

✨ Hosted KYC

🔑 Authentification

🔌 Endpoints

Vérification Biométrique (Liveness)

Gestion API

🔔 Webhooks & Callbacks

URL de Callback (recommande)

Webhooks (avance)

Evenements disponibles

Signature de sécurité

💻 Exemples de code

⚠️ Gestion des erreurs

Prêt à intégrer BloKYC ?