> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de vérification par portefeuille d'identité numérique

> Vérifiez l'identité via un portefeuille d'identité numérique depuis votre application, sans créer de workflow de vérification avec Didit.

Utilisez un endpoint dédié aux portefeuilles pour vérifier une personne depuis votre propre application.
Vous n'avez pas besoin de créer ni de publier un workflow, ni de fournir un `workflow_id`.
Votre backend lance la vérification et récupère son résultat ; votre interface guide la personne dans l'authentification requise par le portefeuille.

> [!NOTE]
>
> Une intégration par API exige toujours que la personne s'authentifie et approuve le partage de son identité.
> Vous ne pouvez pas vérifier quelqu'un en envoyant son identifiant personnel sans cette interaction.

## Fonctionnement de la vérification

1. Votre backend consulte le [catalogue des portefeuilles](https://docs.didit.me/fr/standalone-apis/digital-id-wallet-catalog.md), puis appelle l'endpoint de démarrage d'un portefeuille disponible avec la clé API de votre application.
2. Didit renvoie une référence de vérification et l'action que la personne doit effectuer.
3. Votre application ouvre la page d'authentification ou affiche les instructions d'approbation du portefeuille.
4. La personne s'authentifie avec son portefeuille.
5. Votre backend récupère le résultat vérifié et traite les notifications de fin.

L'authentification par portefeuille est asynchrone.
Une requête de démarrage réussie signifie que l'authentification a commencé ; elle ne signifie pas que l'identité a été vérifiée.
Vérifiez toujours le résultat final avant de considérer la personne comme vérifiée.

## Intégration backend

Utilisez [Lister les portefeuilles d'identité numérique](https://docs.didit.me/fr/standalone-apis/digital-id-wallet-catalog.md) pour obtenir les endpoints actuels, les champs requis et la disponibilité pour votre application.

Conservez votre `x-api-key` sur votre backend.
Ne la placez pas dans un bundle navigateur ni dans une application mobile.
Utilisez un `Idempotency-Key` distinct pour chaque nouvelle tentative de vérification, et réutilisez cette clé lorsque vous relancez la même requête de démarrage.
Modifier la requête tout en réutilisant sa clé constitue un conflit, et non une nouvelle tentative de vérification.

Chaque portefeuille a sa propre URL de démarrage, par exemple `/v3/id-verification/wallets/ftn/` pour Finnish Trust Network.
Le `request_id` identifie la vérification autonome pour les opérations suivantes.
Utilisez `vendor_data` pour votre propre référence, jusqu'à 2,000 octets UTF-8, et `metadata` pour un objet JSON facultatif.
Les deux sont renvoyés avec le résultat et le webhook de fin.

| Opération | Endpoint |
| - | - |
| Lire le statut et le résultat | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Interroger une approbation par téléphone | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Soumettre une réponse du portefeuille Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Annuler une vérification en attente | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Ces opérations utilisent la clé API de l'application qui a lancé la vérification.
L'interrogation et la disponibilité de l'authentification dépendent du portefeuille sélectionné.

Une annulation refuse une vérification en attente sans la facturer, et renvoie une vérification terminée sans la modifier.
Pour Smart-ID et Mobile-ID, une annulation reçue pendant qu'une interrogation vérifie l'approbation attend quelques secondes que cette interrogation se termine.
Elle refuse ensuite la vérification, ou la renvoie avec le statut `verified` si la personne avait déjà approuvé.
Une vérification que la personne est en train de finaliser à ce moment-là ne peut pas être annulée : la réponse est `409` avec `error: "verification_in_progress"` et un en-tête `Retry-After`.
Réessayez après ce nombre de secondes pour lire le résultat final.

## Enregistrer votre destination de retour

Les portefeuilles à redirection renvoient la personne vers votre application après l'authentification.
Enregistrez le nom d'hôte exact avant de lancer une vérification :

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

Envoyez ensuite un `return_url` HTTPS, par exemple `https://app.example.com/identity/complete`, dans la requête de démarrage.
Utilisez uniquement les noms d'hôte dans `allowed_return_hosts`, sans schéma, chemin ni caractère générique.
Enregistrez séparément chaque sous-domaine que vous utilisez, jusqu'à 20 noms d'hôte.
La mise à jour de `allowed_return_hosts` remplace la liste enregistrée ; incluez donc chaque nom d'hôte que vous souhaitez conserver.
`GET /v3/webhook/` renvoie la liste actuelle ; voir [Configuration des webhooks](https://docs.didit.me/fr/sessions-api/management-api.md#configuration-du-webhook).
Vous n'avez besoin ni de workflow ni de domaine en marque blanche pour enregistrer une destination de retour.
Cette destination est une page de retour dans le navigateur ; configurez séparément les webhooks de fin pour votre backend.

## Exemple : Finnish Trust Network

Après avoir enregistré votre nom d'hôte de retour, lancez une vérification auprès de Finnish Trust Network :

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

Conservez le `request_id` renvoyé et redirigez le navigateur de la personne vers `wallet_verification.next_action.url` lorsque son `type` est `redirect`.
Une fois que la personne revient, récupérez le résultat depuis votre backend :

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Vérifiez `wallet_verification.outcome` :

| Résultat | Signification |
| - | - |
| `pending` | L'authentification est toujours en cours. |
| `verified` | L'authentification est terminée et l'identité renvoyée est vérifiée. |
| `cancelled` | La personne ou votre application a annulé la tentative. |
| `timeout` | La fenêtre d'authentification a expiré. |
| `failed` | L'authentification ou la validation de l'identité a échoué. |

Utilisez l'identité uniquement lorsque le résultat est `verified` et que `simulated` vaut `false` pour une vérification d'identité réelle.
Une réponse en attente peut contenir une action suivante ; les réponses finales n'ont aucune action suivante.

## Expériences d'authentification

**Les portefeuilles avec redirection** renvoient une URL d'authentification.
Ouvrez cette URL dans le navigateur de la personne, laissez-la effectuer le processus d'authentification du portefeuille, puis renvoyez-la vers la destination enregistrée.
Lisez le résultat depuis votre backend au lieu de considérer un paramètre de l'URL de retour comme preuve d'identité.

**Smart-ID et Mobile-ID** utilisent une demande d'approbation sur le téléphone de la personne.
Votre interface collecte l'identifiant personnel requis ; Mobile-ID exige également le numéro de téléphone associé.
Affichez le code de comparaison et demandez à la personne d'approuver uniquement si celui-ci correspond au code affiché sur son téléphone.
Son code PIN doit être saisi dans l'invite d'authentification du portefeuille ou du téléphone, jamais dans votre formulaire ni dans une requête API.
Interrogez votre backend toutes les `poll_interval_seconds` secondes pour obtenir des informations sur l'invite.
Didit vérifie aussi en arrière-plan les approbations téléphoniques en attente ; la notification de fin de vérification peut donc parvenir à votre webhook après que la personne a fermé votre page.

**Google Wallet** est sollicité depuis votre propre page ou application via l'API Digital Credentials, sans redirection ; voir [Portefeuilles Digital Credentials (Google Wallet)](#portefeuilles-digital-credentials-google-wallet).

Le mode d'interaction disponible dépend du portefeuille sélectionné.
Ne partez pas du principe que chaque portefeuille prend en charge un formulaire intégré, un code QR ou une authentification sans navigateur.

## Portefeuilles Digital Credentials (Google Wallet)

Google Wallet est sollicité directement par votre page web ou votre application Android, à l'aide de l'API W3C Digital Credentials.
Il n'y a ni redirection, ni page hébergée par Didit, ni code QR Didit.
Il est disponible en production et dans le sandbox.
Les applications sandbox n'ont pas besoin d'enregistrement ; chaque application de production s'enregistre une seule fois depuis la console (étape « Vérification d'identité », ligne Google Wallet, **S'enregistrer auprès de Google**) avant de pouvoir utiliser Google Wallet.
Consultez [Lister les portefeuilles d'identité numérique](https://docs.didit.me/fr/standalone-apis/digital-id-wallet-catalog.md) pour savoir ce que votre application peut lancer dès maintenant.

**1. Commencer par l'origine**

Votre backend appelle `POST /v3/id-verification/wallets/google-wallet/` avec le `country` de la personne (`USA`, `GBR`, `BRA`, `SGP` ou `TWN`) et l'`origin` qui sollicitera le portefeuille.
L'`origin` est l'origine HTTPS de votre page, par exemple `https://app.example.com`, dont l'hôte doit figurer parmi vos [noms d'hôte de retour enregistrés](#enregistrer-votre-destination-de-retour) ou être votre domaine en marque blanche.
Pour une application Android, elle correspond à `android:apk-key-hash:` suivi du SHA-256 en base64 du certificat de signature de votre application, sans remplissage.
Le portefeuille refuse toute requête émise depuis une autre origine.
Il n'existe pas de `return_url`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. Demander le portefeuille lors d'une action de l'utilisateur**

La réponse contient `wallet_verification.interaction = "digital_credentials"` et `next_action.type = "request_digital_credential"`.
Transmettez `next_action.digital_credentials.request` au navigateur ou à Android Credential Manager, à partir d'un appui ou d'un clic sur l'`origin` que vous avez utilisée au départ.
Sur ordinateur, le navigateur affiche son propre code QR lorsque le portefeuille se trouve sur un autre appareil.

**3. Envoyer la réponse renvoyée par le portefeuille**

Envoyez le `{protocol, data}` renvoyé à votre backend, puis depuis celui-ci à `POST /v3/id-verification/wallets/verifications/{request_id}/response/` sous la forme `{"response": {...}}`.
La requête ne peut être envoyée qu'une seule fois ; un second envoi renvoie la vérification déjà décidée.

**4. Lire le résultat**

La réponse à l'envoi correspond à la vérification décidée.
Vous pouvez aussi la lire avec `GET /v3/id-verification/wallets/verifications/{request_id}/` ou la recevoir dans le webhook de fin de vérification.

Dans le navigateur, sollicitez le portefeuille depuis un gestionnaire de clic :

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

Proposez cette méthode uniquement lorsque le navigateur la prend en charge, par exemple lorsque `"DigitalCredential" in window` est vrai.
`navigator.credentials.get` doit s'exécuter dans une action de l'utilisateur ; appelez-le donc depuis le gestionnaire de clic et non après une étape asynchrone.

Sur Android, utilisez Jetpack Credential Manager (`androidx.credentials` 1.5.0 ou version ultérieure) avec la même requête :

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Erreurs à gérer :

| Erreur | Où | Signification |
| - | - | - |
| `origin_invalid` | Démarrage, `400` | `origin` n'est ni une origine HTTPS ni une origine d'application Android. |
| `origin_not_allowed` | Démarrage, `400` | L'hôte de l'origine n'est pas enregistré pour votre application. Ajoutez-le dans `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Envoi, `409` | Cette vérification n'accepte pas de réponse de portefeuille. |

Un justificatif qui échoue à la vérification correspond à une vérification décidée avec un résultat `failed`, et non à une réponse d'erreur.
Seuls les champs demandés par la vérification sortent du portefeuille, et le résultat contient les attributs d'identité que le portefeuille a renvoyés.
Un pass d'identité Google Wallet ou un permis de conduire mobile d'un État américain ne renvoie pas de portrait.

Dans une application sandbox, le parcours est simulé avec les mêmes étapes et renvoie `simulated: true`.
Toute réponse envoyée décide de la vérification selon le `sandbox_scenario`, ce qui vous permet de construire le parcours complet dans le navigateur ou dans l'application sans justificatif réel.

## Webhooks de fin de vérification

Configurez une destination de webhook d'application pour `status.updated` en suivant le [guide d'intégration des webhooks](https://docs.didit.me/fr/integration/webhooks.md).
Utilisez `webhook_version: "v3"` pour la structure de décision décrite ici.
Vérifiez la signature du webhook sur votre backend avant de le traiter.
Le `session_id` du webhook correspond au `request_id` renvoyé par l'API du portefeuille.
Une identité de portefeuille vérifiée apparaît dans le tableau `decision.id_verifications` du webhook avec `verification_method: "wallet"`.
Vous pouvez aussi utiliser cet identifiant pour récupérer le résultat dédié de l'API du portefeuille.

Traitez les notifications d'approbation et de refus, y compris les vérifications annulées et expirées.
Rendez votre gestionnaire de webhook idempotent, car les envois échoués sont relancés.
Un retour depuis le navigateur n'est pas un webhook de fin de vérification, et ses paramètres de requête ne constituent pas une preuve d'identité.

## Identité retournée

Utilisez les champs d'identité normalisés pour les noms et les dates de naissance lorsque ces champs sont retournés.
Les attributs propres au portefeuille décrivent les informations d'identité partagées par le portefeuille sélectionné.
Les attributs disponibles varient selon le portefeuille et le pays.
Une identité authentifiée n'implique pas qu'un portrait, une adresse ou tout autre attribut demandé soit disponible.

## Test en sandbox

Une application en mode sandbox de Didit simule la vérification par portefeuille sans contacter de fournisseur de portefeuille et sans débiter de crédits.
La réponse identifie ces requêtes avec `wallet_verification.simulated: true`.
Une approbation simulée correspond à des données d'exemple, et non à une identité réelle vérifiée.

Pour un portefeuille à redirection, suivez l'URL retournée afin de tester le rappel et le retour vers votre application.
Pour Smart-ID ou Mobile-ID, utilisez l'endpoint d'interrogation pour finaliser l'approbation simulée ; aucune notification n'est envoyée sur un téléphone.
Pour tester la gestion des échecs, définissez `sandbox_scenario` sur `wallet_cancelled`, `wallet_timeout` ou `wallet_provider_error` lors du lancement d'une requête.
Les applications en production rejettent `sandbox_scenario`.

La simulation sandbox de Didit est distincte des tests effectués dans l'environnement de test propre à un fournisseur.
Une simulation réussie n'établit ni l'accès en production auprès d'un fournisseur ni la disponibilité en production.

### Sandbox du fournisseur ConnectID

Le sandbox du fournisseur ConnectID utilise des banques de test et est distinct de la simulation sandbox de Didit.
Lorsque l'accès au sandbox du fournisseur est configuré pour votre intégration, transmettez l'`authorisation_server_id` de la banque sélectionnée à l'[endpoint de démarrage ConnectID](https://docs.didit.me/fr/api-reference/digital-id-wallets/connectid.md).
Utilisez l'identifiant retourné par le sélecteur de banques ConnectID ; n'envoyez ni URL de banque ni émetteur arbitraire.
Si vous omettez ce champ, la banque de test par défaut est sélectionnée.
Ce champ est propre à ConnectID et ne modifie pas les attributs d'identité demandés.

Le lot initial demande le prénom, le nom de famille et la date de naissance.
Suivez le `next_action` retourné pour vous authentifier, puis récupérez ou interrogez le résultat de la vérification.
Seul un résultat terminé avec un statut approuvé confirme que la vérification a réussi ; le retour vers votre application ne suffit pas à le confirmer.
ConnectID reste **bientôt disponible** en production pendant la finalisation de l'onboarding et de la certification.

## Disponibilité et tarifs

La couverture des endpoints et l'activation des portefeuilles en production sont distinctes.
Un portefeuille peut disposer d'une page de référence de l'API tout en restant indisponible pour l'authentification en production.
Vérifiez la couverture géographique par pays et le statut de production du portefeuille avant de mettre en œuvre un parcours en production.

Consultez les [tarifs des portefeuilles d'identité numérique](https://docs.didit.me/fr/getting-started/pricing.md#tarifs-des-portefeuilles-d’identité-numérique) pour les tarifs publiés et la disponibilité.
La vérification par portefeuille est facturée séparément de la capture de documents.

## Choisir une intégration

Utilisez ces API lorsque vous souhaitez gérer vous-même l'interface et la logique applicative qui l'entourent.
Utilisez l'[API Sessions](https://docs.didit.me/fr/sessions-api/create-session.md) lorsque vous souhaitez bénéficier du parcours de vérification hébergé par Didit, des règles de workflow et des étapes de repli configurées.
Les deux approches exigent tout de même le processus d'authentification et de consentement du portefeuille.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.