Gestion des erreurs
Afin que votre implémentation de l'API Accounts soit optimale, il est nécessaire de bien comprendre le statut des connexions, les problèmes qui en sont la cause, et les actions à votre disposition pour les résoudre.
Tout d'abord, l'intégrateur doit récupérer le statut de la connexion pour la dernière synchronisation effectuée (automatique par Linxo ou manuelle par le partenaire), afin de savoir si celle-ci s'est correctement exécutée. Les différents cas de figure :
- La connexion est en
SUCCESS: aucune action n'est à prévoir. - La connexion est en PARTIAL_SUCCESS ou FAILED : il est alors nécessaire de vérifier le statut des channels qui composent la connexion.
L'ensemble des statuts d'erreur des connexions, channels et comptes, sont détaillés sur notre DevPortal :
https://developers.oxlin.io/reference-accounts-api/#section/Description
Une fois que l'intégrateur a identifié l'erreur, plusieurs options s'offrent à lui :
Appel au endpointedit_credentials
Côté utilisateur, un parcours s'ouvre au sein du Widget Linxo Connect, afin qu'il saisisse à nouveau ses identifiants sur le channel ciblé.
Pour effectuer ce 'ciblage', les intégrateurs doivent rajouter le paramètre expected_account_types dans leur appel au edit_credentials.
- Si expected_account_types=PAYMENT, le Widget redirigera l'utilisateur vers le site de sa banque pour qu'il renouvelle les identifiants sur le channel DEDICATED_INTERFACE (Redirect).
- Si expected_account_types=OTHER, le Widget proposera à l'utilisateur de saisir à nouveau les identifiants associés au channel DIRECT_ACCESS (Embedded).
- Si expected_account_types=ALL, le widget enchaîne automatiquement le DEDICATED_INTERFACE (si existant) puis le channel DIRECT_ACCESS (si existant).
Les différents paramètres sont également expliqués sur notre DevPortal : https://developers.oxlin.io/docs/accounts-integration-getting-connection-continuous/#edit-credential
A noter que ces statuts peuvent être récupérés via :
- L’API, avec le GET /connection
https://developers.oxlin.io/reference-accounts-api#tag/manage-connection/operation/getConnectionsUsingGET - Le webhook, qui remonte également les informations des connexions à chaque synchronisation des comptes
https://developers.oxlin.io/docs/accounts-integration-webhooks-continuous - La gestion des événements du widget (événements web) ou via une queue permet également de récupérer des informations en temps réel.
https://developers.oxlin.io/docs/accounts-tools-event-js
https://developers.oxlin.io/docs/accounts-integration-using-queue-events/
Appel au endpointmanage_connections
Le endpoint manage_connections permet aux utilisateurs de solutionner la plupart des cas d’erreurs en toute autonomie. Il s’agit d’un centre de contrôle qui liste toutes les connexions de l’utilisateur, et qui affiche les statuts d’erreurs à l’aide de messages contextuels.
L’intégrateur, s’il détecte une connexion en erreur, peut prévoir un bouton au sein de son interface pour rediriger l’utilisateur vers le manage_connections. Il peut également laisser un bouton de manière permanente, pour permettre à l’utilisateur de naviguer sur l'écran, et gérer ses connexions.
Les possibilités apportées par le manage_connections étant multiples, nous vous invitons à consulter la page qui lui est dédiée au sein de de notre DevPortal.
Gestion des Challenges
Lors de la synchronisation manuelle des canaux DIRECT_ACCESS (réservés au compte d’Epargne et de Crédit), les établissements bancaires peuvent envoyer des demandes de ‘challenge’. Il s’agit en fait d’une demande de SCA, que l’utilisateur doit obligatoirement effectuer : sans cela, la synchronisation de ses données bancaires ne sera pas effectuée.
Cette SCA peut être de 2 types :
- Code : l’utilisateur doit saisir un code qu’il a reçu par SMS sur son téléphone personnel
- Decouplé : l’utilisateur doit valider sa demande de connexion sur l’application de sa banque
A noter que lors de la création d’une connexion, ce flow est entièrement pris en charge par le Widget, sans actions nécessaires de la part de l’intégrateur.
Afin de gérer ces challenges, plusieurs actions sont possibles côté intégrateur :
Appel au endpointuser_input
Ce endpoint permet de gérer en temps réel la demande de challenge de la banque. Le flow d’utilisation du user_input se déroule comme suit :
- L’intégrateur souscrit à un queue via le POST /queues/subscribe
- L’intégrateur déclenche une synchronisation manuelle via le endpoint POST /synchronize
- L’intégrateur écoute les events de la queue via le endpoint GET /queues
Le déclenchement des events suivants signifie que la banque nécessite que l'utilisateur réalise un challenge : SYNC_ALL_USER_INPUT_REQUESTED, LIST_ACCOUNTS_USER_INPUT_REQUESTED
- L’intégrateur appelle le endpoint user_input pour que l’utilisateur puisse honorer la demande de challenge. Comme vu plus haut, il existe 2 cas de figure :
- Code : la banque envoie un code par SMS, que l’utilisateur doit saisir dans le Widget. Un appel au user_input permet alors d’afficher le formulaire de saisie. Après saisie et validation, la synchronisation se déclenche.
- Challenge ‘Découplé’ : l’appel au user_input permet d’afficher le Widget, qui demande à l’utilisateur de valider la SCA sur l’application de sa banque. Une fois l’action effectuée, il peut cliquer sur le call-to-action affiché dans le Widget, ce qui déclenche la synchronisation.
La documentation de référence portant sur le user_input est disponible sur cette page :
https://developers.oxlin.io/reference-accounts-api#tag/manage-widget/paths/~1v2.1~1widget~1user_input/get
Il est à noter que l’ensemble du workflow peut être complexe à mettre en place. Il existe d’autres alternatives plus simples, détaillées ci-dessous.
Appel au endpointedit_credentials
Dans le cas où les événements ne sont pas utilisés, la gestion des challenge n’est pas effectuée en temps réel mais en fonction du statut d’erreur de la dernière synchronisation.
Typiquement, la synchronisation a temporairement été en statut CHALLENGE_REQUIRED, mais le challenge n’a pas été honoré par l’utilisateur, ou bien a été annulé par ce dernier. Au bout d’un certain laps de temps, le channel peut hériter de l’un des statuts suivants :
-
CHALLENGE_FAILED -
CHALLENGE_CANCELLED -
CHALLENGE_TIMED_OUT
A posteriori, l’intégrateur peut alors appeler le endpoint edit_credentials. Cette action déclenche a une nouvelle saisie des identifiants, et permet de relancer la synchronisation en cas de saisie correcte.
A noter que la description des statuts d’erreurs, et leurs actions de résolution si listées dans le tableau en fin d’article.
Appel au endpointmanage_connections
Le manage_connections permet aussi aux utilisateurs de visualiser une demande challenge émis par une banque pour la synchronisation d’un de ses channels.
Les possibilités apportées par le manage_connections étant multiples, nous vous invitons à consulter la page qui lui est dédiée au sein de de notre DevPortal.
Une fois que le statut du channel (ou de la connexion) est repassé en SUCCESS, la synchronisation est de nouveau opérationnelle.
Pour résumer les statuts possibles et les actions associées, nous vous proposons de consulter ce tableau récapitulatif :
|
Statut du channel |
Type de channel pouvant être impacté |
Description du statut | Endpoints pouvant être appelés par l'intégrateur | |||
| PARTIAL_SUCCESS |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation s'est déroulée avec succès, mais certains comptes n'ont pas pu être actualisés (par exemple s'ils ne sont plus disponibles sur le site de la banque) | NA | NA | NA |
| FAILED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué en raison d'un erreur technique. L'intégrateur peut effectuer une synchronisation via POST /synchronize pour vérifier si le problème persiste |
manage_ connections (pour proposer à l'utilisateur de déclencher une synchro manuelle) |
NA | NA |
| AUTH_FAILED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
L'authentification a échoué lors de la dernière synchronisation du canal |
manage_ connections |
edit_ credentials |
user_input |
| TOO_MANY_ATTEMPTS |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
L'authentification a échoué plusieurs fois d'affilée. La synchronisation des canaux est suspendue jusqu'à ce que le user se ré-authentifie |
manage_ connections |
edit_ credentials |
user_input |
| TOKEN_EXPIRED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
Le token API a expiré |
manage_ connections |
edit_ credentials |
user_input |
|
SERVICE_ UNAVAILABLE |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
Le site ou l'API du provider n'était pas disponible lors de la dernière synchronisation |
manage_ connections |
edit_ credentials |
user_input |
|
PASSWORD_ CHANGE_REQUIRED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car le provider requiert un changement de mot de passe |
manage_ connections |
edit_ credentials |
user_input |
|
USER_ACTION_ REQUIRED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car le provider requiert action de l'utilisateur (accepter les nouvelles conditions d'utilisations, remplir un formulaire etc...) |
manage_ connections |
edit_ credentials |
user_input |
|
CHALLENGE_ REQUIRED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car le provider a fait une demande de challenge (par SMS, mail etc...). L'utilisateur n'était pas l'initiateur de cette synchronisation. |
manage_ connections |
edit_ credentials |
user_input |
| CHALLENGE_FAILED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car l'utilisateur a répondu de manière incorrecte au challenge. |
manage_ connections |
edit_ credentials |
user_input |
|
CHALLENGE_ CANCELLED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car l'utilisateur a annulé la demande de challenge. |
manage_ connections |
edit_ credentials |
user_input |
|
CHALLENGE_ TIMED_OUT |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
La dernière synchronisation a échoué car l'utilisateur n'a pas répondu au challenge dans le temps imparti. |
manage_ connections |
edit_ credentials |
user_input |
| EMPTY |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
Aucun channel n'a été créé. |
NA |
NA | NA |
| CLOSED |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
Le channel a été fermé et ne sera plus synchronisé. |
NA |
NA |
NA |
| NEVER |
DEDICATED_ INTERFACE (Redirect) |
DIRECT_ ACCESS (Embedded) |
Le channel n'a encore jamais été synchronisé. | NA | NA | NA |