AYAEL KYC

Démarrer

Demandez d'abord un bac à sable — recharge-sandbox, edvis-sandbox — et non votre accès de production : vous y déroulerez tout ce qui suit sans qu'une identité d'essai puisse atteindre un dossier réel.

L'administrateur d'AYAEL enregistre l'application depuis le back-office, page Applications. Ni accès au serveur, ni redémarrage : les vérifications en cours ne sont pas interrompues. Il vous remet alors trois choses.

L'identifiant de votre application (recharge-sandbox, mma…) devient son source_app : il apparaît dans le back-office et dans chaque webhook. Il est définitif, car c'est lui que portent les dossiers déjà enregistrés — et le nom d'affichage ne se modifie pas davantage aujourd'hui. Prévoyez-le parlant, surtout si vous aurez un bac à sable et un accès de production côte à côte.

La règle qui prime sur les autres

La clé de service ne part jamais dans une application mobile ni dans une page web. Elle vit sur votre serveur.

Une clé embarquée dans un binaire mobile est extractible — c'est une question d'outillage, pas de difficulté — et elle ouvre alors l'accès à tous les dossiers de votre application, pas seulement à celui de son porteur.

Le parcours

Créer le dossier, déposer les images, finaliser, puis attendre le webhook. Toutes les requêtes portent l'en-tête X-API-Key.

Les images attendues

Ces six valeurs sont les seules acceptées : toute autre répond 400. Le nom du fichier que vous envoyez n'est pas conservé — AYAEL nomme lui-même ce qu'il écrit, et se fie au Content-Type de la partie file pour l'extension.

Finaliser

POST /kyc/cases/{case_id}/submit
X-API-Key: ayl_recharge_…

{
  "declared_data": {
    "first_name": "Aya",
    "last_name": "Kouassi",
    "dob": "1992-04-17"
  },
  "document_type": "CNI",
  "document_country": "CI",
  "liveness_challenge": "BLINK"
}

dob au format AAAA-MM-JJ. Nom, prénom et date de naissance alimentent la détection de doublons et la comparaison avec la pièce : des champs vides affaiblissent les deux. liveness_challenge vaut BLINK ou TURN, et seulement si les trois images de vivacité ont été déposées.

Statuts

La vérification dure de quelques secondes à deux minutes. Le résultat arrive par webhook.

Reprendre après une correction

Un dossier = une tentative. Il se vérifie une seule fois, et son statut ne bouge plus ensuite — sauf décision d'un opérateur.

Pour faire reprendre quelqu'un après un CORRECTION_REQUIRED, ouvrez un nouveau dossier avec le même user_id, redéposez les pièces et soumettez-le. C'est le user_id qui relie les tentatives entre elles, pas le case_id.

POST /kyc/cases                      { "user_id": "4312" }   ← un id neuf
POST /kyc/cases/{nouveau}/document?kind=…                    ← toutes les pièces
POST /kyc/cases/{nouveau}/submit

Redéposez toutes les pièces, pas seulement celle que correction_reason désigne : le nouveau dossier repart de zéro, et une pièce manquante ferait échouer le contrôle correspondant.

Au bout de trois corrections, le dossier part en revue humaine plutôt que d'en demander une quatrième. C'est le décompte des tentatives précédentes du même user_id qui le déclenche — raison de plus pour le garder identique d'une reprise à l'autre.

Le détail des contrôles : normalized_result

GET /kyc/cases/{id} renvoie aussi ce que les contrôles automatiques ont conclu. Vous n'en avez pas besoin pour le parcours — status et correction_reason suffisent — mais c'est ce qui permet à votre propre back-office de montrer à vos opérateurs pourquoi un dossier attend, sans ouvrir celui d'AYAEL.

Codes de correction

AYAEL envoie un code, jamais une phrase : SELFIE_UNREADABLE, DOCUMENT_UNREADABLE, LIVENESS_FAILED, DATA_MISMATCH, FACE_MATCH_UNCERTAIN, DOCUMENT_NOT_ORIGINAL.

DOCUMENT_NOT_ORIGINAL signale qu'une reproduction a été photographiée — l'écran d'un téléphone affichant la pièce, ou une photocopie — et non le document lui-même. Demandez à l'utilisateur de photographier la pièce physique.

La formulation montrée à l'utilisateur vous appartient — vous seul savez vous adresser à lui, dans sa langue et avec vos mots. Prévoyez un message par code, et un message de repli pour un code que vous ne connaîtriez pas encore.

Le champ sandbox

Présent partout où AYAEL rend un dossier. Vrai quand il vient d'une application de mise au point.

Un dossier d'essai n'a été comparé qu'à d'autres essais : la recherche de doublons n'a rien couvert le concernant. Deux façons correctes d'en tenir compte :

Refuser la vérification par code — le plus sûr, si vous n'avez pas besoin d'aller au bout de votre parcours pendant les essais :

if (dossier.sandbox) return;   // aucun compte n'est vérifié par un essai

L'accepter, mais l'enregistrer — si vous devez éprouver tout votre parcours en conditions réelles, un achat derrière la vérification par exemple. Gardez le champ avec le compte, et remettez ces comptes à « non vérifié » le jour de la bascule.

Dans les deux cas, c'est ce champ qu'il faut lire, pas le suffixe du source_app : -sandbox n'est qu'une convention de nommage.

L'identité lue sur la pièce

Présente uniquement sur un dossier approuvé — dans le webhook, dans GET /kyc/cases/{id} et dans la liste GET /kyc/cases, sous verified_identity. Brute, en majuscules.

Reprenez-la à la place du nom saisi à l'inscription. Sans cela vous gardez indéfiniment ce que l'utilisateur avait tapé. Le cas s'est produit : un client corrigeait son prénom à chaque tentative, la vérification passait avec la valeur corrigée, et le formulaire suivant repartait de l'ancienne.

La mise en forme vous appartient également : AYAEL sert plusieurs applications et n'a pas à décider comment chacune affiche un nom.

Et avant l'approbation : declared_data

Sur un dossier qui n'est pas approuvé, verified_identity vaut null — une lecture de pièce n'atteste rien tant que le dossier n'est pas tranché. Pour savoir de qui il s'agit, lisez declared_data : ce que votre utilisateur avait saisi, tel que vous nous l'avez transmis. Rendu quel que soit le statut, partout où AYAEL rend un dossier.

C'est votre donnée : nous vous la rendons pour que votre back-office affiche une file d'attente lisible sans garder sa propre copie des identités.

Webhook

À chaque changement de statut, AYAEL envoie un POST à l'URL déclarée, avec un en-tête X-Ayael-Signature — HMAC-SHA256 du corps exact, en hexadécimal, avec votre secret de signature.

{
  "event": "case.status_changed",
  "case_id": "2f6c…",
  "user_id": "l-identifiant-chez-vous",
  "status": "APPROVED",
  "source_app": "recharge",
  "sandbox": false,
  "correction_reason": null,
  "verified_identity": { "first_name": "AYA", "last_name": "KOUASSI", "dob": "1992-04-17" }
}

Vérifier la signature

Signez les octets reçus, jamais un objet re-sérialisé : votre encodeur JSON ne produira pas les mêmes octets que l'émetteur — espaces, ordre des clés — et la vérification échouera pour de mauvaises raisons. Comparez en temps constant, jamais avec == : une comparaison qui s'arrête au premier octet différent laisse deviner la signature attendue, essai après essai.

$corps = file_get_contents('php://input');
$recue = $_SERVER['HTTP_X_AYAEL_SIGNATURE'] ?? '';
$attendue = hash_hmac('sha256', $corps, $secret);

if (!hash_equals($attendue, $recue)) {
    http_response_code(401);
    exit;
}

const corps = await req.text();
const recue = req.headers.get("X-Ayael-Signature") ?? "";
const attendue = await signatureHex(secret, corps);

if (!memeSignature(attendue, recue)) {
  return new Response("signature invalide", { status: 401 });
}

Les pièces du dossier

Montrer à vos administrateurs la pièce et le selfie déposés, sans en garder une copie chez vous. Ouvert sur vos propres dossiers : ce sont les images que vous avez déposées.

Rien à demander depuis le 24/09/2026. Le dossier d'une autre application reste un 404, comme partout ailleurs ; un 403 signifie que l'accès a été retiré à votre application, ce qui n'arrive qu'en cas d'abus constaté.

Ce que les applications partagent

La recherche de doublons est volontairement globale : un même individu passant d'un produit à l'autre est précisément ce qu'on veut voir.

Un dossier ouvert chez vous est donc comparé à ceux de toutes les applications servies, et réciproquement. Ce qui reste cloisonné : vous ne lisez jamais les dossiers d'une autre application. Un rapprochement signale qu'un dossier jumeau existe ; son contenu n'est visible que dans le back-office, par un opérateur.

Un doublon ne rejette jamais tout seul : il envoie le dossier à un humain. Depuis le 01/10/2026 c'est le visage qui qualifie le rapprochement : SAME_PERSON (même identité, même visage, jumeau déjà approuvé) laisse l'approbation automatique s'appliquer — une personne présente sur deux plateformes ne déclenche plus de revue à chaque fois ; IDENTITY_CONFLICT (même identité, visage différent) et FACE_REUSED (même visage, autre identité) la déclenchent au contraire, et sont des signaux que le nom seul ne voyait pas.

À savoir : un user_id n'a de sens que dans l'application qui l'a émis. Le vôtre peut coïncider avec celui d'une autre sans désigner la même personne — AYAEL en tient compte, vous n'avez rien à faire de particulier.

Essayer sans rien salir

Demandez votre bac à sable, pas un bac à sable commun : il porte un identifiant propre — recharge-sandbox, mma-sandbox — et sa propre clé.

Vider votre bac à sable

Vos dossiers d'essai s'effacent seuls, passé 48 heures sans changement — images comprises. Le balayage est quotidien : la suppression intervient donc entre 48 et 72 heures. Les dossiers de production ne sont jamais concernés.

Passer en production

Le bac à sable ne se transforme pas : vous recevez une seconde application, qui vit à côté de la première. Vous gardez ainsi un endroit où essayer la version suivante de votre intégration sans toucher à vos clients.

Erreurs

Le 404 sur le dossier d'autrui est délibéré : un 403 confirmerait son existence à qui l'interroge au hasard. Le 403, lui, ne porte jamais que sur vos dossiers — c'est pourquoi il peut dire la vérité sans rien révéler.

Collection Postman

Le parcours complet, les filtres de suivi, la décision manuelle et les refus attendus. Copiez, puis dans Postman : Import → Raw text.

Chargement…

Renseignez ensuite base_url et api_key dans l'environnement. La requête « Créer le dossier » enregistre elle-même le case_id pour les suivantes.

Le fichier est aussi téléchargeable : ayael-kyc.postman_collection.json, et la description OpenAPI se trouve sur api.ayaelkyc.com/openapi.json.