OneSpan Developer : Point de fin de validation des transactions
OneSpan Intelligent Adaptive Authentication (IAA) offre le point de terminaison Transaction Validation pour traiter les événements monétaires de manière adaptative. Chaque fois qu'une requête est déclenchée vers l'API Transactions/Validation, Risk Analytics (RA) répondra pour capturer la méthode d'authentification appropriée de l'utilisateur final, en fonction du risque associé à la transaction. Dans le blog d'aujourd'hui, nous allons expliquer comment préparer la demande d'une transaction monétaire à l'aide de l'API interactive de l'Environnement de test et montrer les réponses possibles de l'AE à cet événement
Avant de commencer
Avant d'explorer le point de terminaison de la validation des transactions, vous devez d'abord être membre de la communauté OneSpan et vous inscrire à un compte sandbox gratuit d'Intelligent Adaptive Authentication. Voici les instructions étape par étape sur la façon de procéder.
Vous devez également vous assurer d'avoir au moins un utilisateur enregistré avant d'essayer cet appel. Pour apprendre comment enregistrer un utilisateur, consultez ce blog détaillé sur l'enregistrement d'un utilisateur.
URL du point de terminaison
L'URL de la demande pour cet appel API ressemblera à l'exemple ci-dessous :
https://{votre_ID_locataire}.sdb.tid.onespan.cloud/v1/users/{userID@domain}/transactions/validation
Vous n'aurez pas besoin de fournir cette URL pendant le tutoriel. Il s'agit uniquement de montrer la structure de l'URL. L'URL sera automatiquement attribuée dans l'API interactive lors de l'appel du webservice
Essayez-le
Afin d'expérimenter l'API de validation des transactions, accédez au document IAA Sandbox Interactive API dans votre compte OneSpan Community. Dans l'éditeur Open API Swagger, développez la ressource "Transactions". Vous trouverez ensuite une entrée pour la méthode Transactions/Validate HTTP Post, comme le montre l'image ci-dessous
![OneSpan-BlogImage [Transaction-Validation-Endpoint]1](/sites/default/files/inline-images/OneSpan-BlogImage%5BTransaction-Validation-Endpoint%5D1_0.png)
Paramètres du chemin URL :
Aux fins de l'appel API Transaction/Validation, un paramètre de chemin d'accès est requis pour l'identifiant unique de l'utilisateur. Il sera formaté comme suit : userID@domain. Un exemple de l'ID utilisateur est "iaa_user". Il s'agit de l'ID utilisateur qui a été activé sur le dispositif de confiance. La partie du paramètre qui suit le signe "@" est le domaine de l'utilisateur. Cette entrée doit être remplacée par la chaîne "Sandbox User" présentée ci-dessous, qui est présente dans la section des détails de votre Sandbox sous l'onglet "Intelligent Adaptive Authentication" de la page d'accueil de votre Sandbox.
![OneSpan-BlogImage [Transaction-Validation-Endpoint]2](/sites/default/files/inline-images/OneSpan-BlogImage%5BTransaction-Validation-Endpoint%5D2_0.png)
Corps de la demande de validation de la transaction
Dans la section "Request Body" du point final Transaction/Validate, sélectionnez le type d'objet "AdaptiveTransactionValidationInput" dans le menu déroulant, comme indiqué ci-dessous. Vous obtiendrez alors un exemple de la charge utile de la requête JSON requise par le point de terminaison de la validation des transactions
![OneSpan-BlogImage [Transaction-Validation-Endpoint]3](/sites/default/files/inline-images/OneSpan-BlogImage%5BTransaction-Validation-Endpoint%5D3_0.png)
Le corps de la demande ressemblera à l'exemple ci-dessous des champs obligatoires du point de terminaison Transaction/Validate.
{ "objectType" : "AdaptiveTransactionValidationInput", "accountRef" : "ACC123", "amount" : "1064.99", "cddc" : { "browserCDDC" : { "fingerprintRaw" : "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1 ; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}", "fingerprintHash" : "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7" } }, "currency" : "EUR", "data" : { "transactionMessage" : { "dataFields" : [
Charge utile de la demande
Il contient deux objets JSON obligatoires présentés dans le tableau :
| Champs de données obligatoires JSON | Description | Champ Type de données |
|---|---|---|
| type d'objet | Il s'agit de déclarer le type d'objet de la transaction dans les données utiles de la demande aux fins de la solution d'authentification adaptative intelligente. |
Type : Enum Exemple : "[ AdaptiveTransactionValidationInput]" |
| compteRef* |
|
Type : objet imbriqué JSON longueur min. : 1 longueur max. : 250 Exemple : Checking_Account_CH53 |
| montant* | La valeur du montant de la transaction | Type : string pattern : ^- ?[0-9]{1,10}(\.[0-9]{1,2})?$ exemple : 999.99 |
| cddc* | Méta-données du collecteur de données du dispositif client. Les deux champs browserCDDC et mobileCDDC sont mutuellement exclusifs et collectivement exhaustifs. | Type : chaîne de caractères Exemple : "browserCDDC" ou "mobileCDDC" |
| relationRef* | La référence relationnelle de l'ID utilisateur. | Type : string minLength : 1 maxLength : 150 Exemple : iaa_user |
| staticPassword* | Le mot de passe statique initial attribué à l'utilisateur. | Type : string minLength : 8 maxLength : 255 exemple : Test1234 |
| identifiant de la session | Identifiant de session d'application formaté sous forme de chaîne hexadécimale ; commun à toutes les transactions liées à la même session | Type : string pattern : ^[0-9a-fA-F]+$ minLength : 2 maxLength : 100 example : 4ed23ea44f23 |
| transactionType* | Ce champ crucial spécifie le type de transaction à envoyer dans la demande. La définition du type de transaction permettra de traiter les différentes transactions de manière unique du côté de Risk Analytics | Type : chaîne de caractères Exemple : ExternalTransferBillPayments, MobileInternalTransfer |
Appeler le point de terminaison
À ce stade, nous sommes prêts à effectuer un appel RESTful vers le point de terminaison Transaction/Validate à l'aide de l'API Sandbox interactive IAA. Pour effectuer l'appel, cliquez sur le bouton "Try it out" illustré dans la capture d'écran ci-dessous et situé à droite de la section relative à la méthode HTTP POST. Une fois la demande effectuée, vous recevrez le corps de la réponse en retour au format JSON. Il sera similaire à la charge utile de la réponse décrite dans la section suivante.
![OneSpan-BlogImage [Transaction-Validation-Endpoint]4](/sites/default/files/inline-images/OneSpan-BlogImage%5BTransaction-Validation-Endpoint%5D4_0.png)
Charge utile de la réponse
Vous trouverez ci-dessous un exemple du corps de réponse renvoyé avec un code de réponse 200 qui indique une transaction réussie.
{ "requestID" : "413b2c39-2d67-4293-9adb-25601731b062", "riskResponseCode" : 0, "sessionStatus" : "accepted", "requestMessage" : "0000F8B81D" }
Description des champs du corps de la réponse
Le "requestID" est le premier champ de la réponse, il s'agit d'une chaîne de 36 caractères utilisée pour garder une référence de l'appel API précédent. Cet ID peut être utile pour le débogage et le référencement.
Le champ "riskResponseCode" est le code de réponse de Risk Analytics. La valeur "0" dans la réponse ci-dessus indique que la demande a été acceptée et que l'utilisateur a été authentifié avec succès sans qu'aucune mesure supplémentaire ne soit nécessaire. Vous trouverez ci-dessous une liste d'autres valeurs possibles qui peuvent être renvoyées par Risk Analytics. En outre, des valeurs supplémentaires peuvent être configurées par le biais du service de présentation de Risk Analytics.
| Comportement d'analyse des risques | Code de réponse au risque (nombre entier) |
|---|---|
| Accepter | 0 |
| Déclin | 1 |
| Défi | 2 |
| ChallengeSMS | 3 |
| ChallengeDevice2FA | 5 |
| ChallengeEmail | 8 |
| DéfiCronto | 11 |
| ChallengeNoPIN | 21 |
| DéfiPIN | 22 |
| ChallengeEmpreinte digitale | 23 |
| ChallengeFace | 24 |
Le champ "sessionStatus" de la réponse JSON représente l'état actuel de la session après l'envoi de la demande. Le tableau ci-dessous énumère les valeurs d'état possibles.
| Statut de la session | Description du statut |
|---|---|
| inconnu | L'état est inconnu et la réponse est traitée en externe |
| en attente de | En attente d'une action de l'utilisateur final |
| accepté | Réalisé avec succès |
| a refusé | Refusé par l'utilisateur final |
| délai d'attente | Le délai a expiré après qu'aucune réponse n'ait été reçue dans le délai imparti |
| échoué | L'échec de la validation de l'OTP |
Le champ "requestMessage" est de type String. Il est utilisé pour transmettre une commande d'orchestration au dispositif de confiance de l'utilisateur final.
Dans ce blog, nous avons vu comment effectuer une transaction monétaire via l'API interactive OneSpan. Dans les semaines à venir, nous verrons d'autres blogs qui concernent le point de terminaison Transaction/Validate. En attendant, si vous avez des questions, n'hésitez pas à nous joindre sur les forums du portail communautaire OneSpan.
OneSpan Sign Developer Community
Rejoignez la communauté OneSpan Sign Developer! Forums, blogs, documentation, téléchargements SDK, et plus encore.
Joignez-vous aujourd'hui