/collect

POST

Recueille l’information et l’état d’une demande.

Collecte le résultat d’une demande avec orderRef comme référence.

Votre service doit continuer d’appeler /collect toutes les deux secondes tant que l’état est pending. Il doit s’arrêter si l’état est failed. L’identité de l’utilisateur est renvoyée quand l’état est complete.

Corps de la requête

application/json

orderRef chaîne Obligatoire

Référence de la demande, renvoyée à sa création.

Exemple

{ "orderRef": "131daac9-16c6-4618-beb0-365768f37288" }

Réponses

200 · Requête réussie

orderRef chaîne Obligatoire

Référence de la demande.

status chaîne Obligatoire

L’état actuel de la demande.

pending : la demande est en cours de traitement ; hintCode décrit l’état. complete : la demande est terminée ; completionData contient les informations. failed : un problème est survenu ; hintCode décrit l’erreur.

hintCode chaîne

Quand la demande est en cours, utilisez le hintCode pour donner des détails et des instructions à l’utilisateur, et continuez d’appeler /collect jusqu’à l’échec ou la fin.

completionData objet

Informations sur l’utilisateur et la demande terminée. Vous devez vérifier ces informations avant de poursuivre, et conserver ces données pour référence, conformité et audit. Voir Vérifier les signatures.

hintCode d’une demande en cours

`hintCode`	Raison	Action de votre service
`outstandingTransaction`	La demande est en cours. L’application ExcelID ne l’a pas encore reçue. Le code passera ensuite à `noClient`, `started` ou `userSign`.	Si vous avez lancé l’application automatiquement, informez l’utilisateur qu’elle s’ouvre (message EM13). Sinon, invitez-le à l’ouvrir (EM1).
`noClient`	La demande est en cours. Aucune application ne l’a reçue.	Si vous avez lancé l’application automatiquement, le lancement a échoué ou ExcelID n’est pas disponible sur l’appareil : informez l’utilisateur (EM2). Sinon, il n’a pas encore ouvert l’application (EM1).
`started`	La demande est en cours. L’application a été lancée avec l’`autoStartToken` mais aucune identité utilisable n’a encore été trouvée.	Informez l’utilisateur des solutions possibles (EM15). `started` n’est pas une erreur : continuez d’appeler `/collect`.
`userCallConfirm`	La demande attend que l’utilisateur confirme qu’il est en appel avec votre organisation.	Aucun message nécessaire.
`userSign`	La demande est en cours. L’application l’a reçue.	Informez l’utilisateur (EM9).
`userStepUp`	L’application attend que l’utilisateur confirme son identité par le contrôle supplémentaire.	Informez l’utilisateur (EM24).
`processing`	L’application a reçu et signé la demande ; le traitement de la signature est en cours.	Informez l’utilisateur (EM21).
Code inconnu	De nouveaux codes peuvent apparaître sans préavis.	Informez l’utilisateur (EM21) et mettez votre implémentation à jour dès que possible.

hintCode d’une demande échouée

C’est un état final. Utilisez le hintCode pour donner des détails à l’utilisateur. Le même orderRef ne doit pas être utilisé pour d’autres appels à /collect.

`hintCode`	Raison	Action de votre service
`expiredTransaction`	La demande a expiré : l’application n’a pas été ouverte, l’utilisateur n’a pas confirmé, ou vous avez appelé `/collect` trop tard.	Informez l’utilisateur (EM8).
`idBlocked`	L’utilisateur a saisi trop de fois un mauvais code de sécurité (5 erreurs), ou son ExcelID est bloqué ou invalide.	Informez l’utilisateur (EM16).
`userCancel`	La demande a été annulée par l’utilisateur.	Informez l’utilisateur (EM6).
`cancelled`	La demande a été annulée, ou le système a reçu une nouvelle demande pour l’utilisateur.	Informez l’utilisateur (EM3).
`startFailed`	L’utilisateur n’a pas fourni son identité, ou l’application ne s’est pas lancée dans le délai. Causes possibles : vous n’avez pas utilisé l’`autoStartToken` au lancement ; l’application n’est pas installée ; l’utilisateur n’a pas d’ExcelID activé.	Informez l’utilisateur (EM17).
`userDeclinedCall`	L’utilisateur a indiqué dans l’application qu’il n’est pas en appel avec votre organisation.	Aucun message nécessaire.
`notSupportedByUserApp`	La demande a été reprise par une application qui ne gère pas la fonction demandée.	Demandez à l’utilisateur de mettre à jour ExcelID (EM23).
`stepUpFailed`	Le contrôle supplémentaire a échoué.	Informez l’utilisateur (EM25).
Code inconnu	De nouveaux codes peuvent apparaître sans préavis.	Informez l’utilisateur (EM21) et mettez votre implémentation à jour.

completionData

user objet

La personne : personalNumber (son numéro d’identité d’État : CNIB ou WURI), name, givenName, surname.

device objet

ipAddress : l’adresse IP vue par ExcelID au moment de la confirmation. Pour un parcours sur le même appareil, comparez-la à l’adresse IP que vous observez pour éviter la fixation de session.

issuer objet

Le partenaire qui a activé l’ExcelID : partner (son nom) et activatedAt (la date d’activation).

authenticationMethod chaîne

fingerprint (empreinte digitale) ou pin (code de sécurité).

stepUp objet

Les contrôles supplémentaires réalisés, si vous en avez exigé.

risk chaîne

low, moderate ou high, si vous avez demandé returnRisk. Voir Indication de risque.

signature, signedPayload, devicePublicKey, completionTime

La preuve de la confirmation et son heure. userNonVisibleData vous renvoie vos données non visibles.

Exemples

Demande en cours

{
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "status": "pending",
  "hintCode": "userSign"
}

Demande terminée

{
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "status": "complete",
  "hintCode": "complete",
  "completionData": {
    "user": {
      "personalNumber": "B1234567",
      "name": "Aïcha Ouédraogo",
      "givenName": "Aïcha",
      "surname": "Ouédraogo"
    },
    "device": { "ipAddress": "196.28.245.10" },
    "issuer": { "partner": "Orange Money", "activatedAt": "2026-11-13T08:52:10Z" },
    "authenticationMethod": "fingerprint",
    "risk": "low",
    "signature": "MEUCIQ…",
    "signedPayload": "excelid:v1:131daac9-…:Q29ubmV4aW9u…:APPROVE",
    "devicePublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…",
    "completionTime": "2026-11-13T09:41:12.380Z",
    "userNonVisibleData": null
  }
}

Demande échouée

{
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "status": "failed",
  "hintCode": "expiredTransaction"
}