Documentation
Documentation
Vue Web mobile

1Introduction

Cette documentation décrit en détail la manière de communiquer avec l’API des services web depuis un appareil mobile. La communication est censée se faire via une WebView ou une technique similaire. L’hypothèse de base est que l’application mobile est capable de communiquer en invoquant des fonctions JavaScript au sein de la WebView et en écoutant les URL invoquées par la `WebView'.

2Sécurité des services web

L’application mobile peut avoir besoin d’un accès direct aux services web. Cependant, la clé MAC de l’utilisateur d’application ne devrait pas être transmise à l’appareil mobile, car cela permettrait à terme à un appareil mobile malveillant de récupérer ces informations. C’est pourquoi nous fournissons une méthode de service web dédiée permettant de créer, pour une transaction de paiement donnée, des TransactionCredentials. Ces identifiants accordent temporairement (15 minutes) la permission de travailler avec la transaction à laquelle les identifiants sont liés. De plus, lorsque les identifiants sont fournis ultérieurement, ils accordent les mêmes permissions que celles de l’utilisateur qui a créé les identifiants temporaires. Cela implique que l’appareil mobile disposera des mêmes permissions que l’utilisateur.

3Flux / Interactions

Le flux est similaire à celui de l’intégration iFrame. Les étapes suivantes résument comment utiliser l’intégration SDK. Nous supposons que la transaction a été créée et que les identifiants de transaction ont été transmis à l’appareil mobile :

  1. Récupérez les modes de paiement disponibles en utilisant l’opération fetchPossiblePaymentMethodsWithCredentials du Transaction Service.

  2. Présentez une liste de modes de paiement à l’utilisateur.

  3. Pour le mode de paiement sélectionné, intégrez le formulaire en appelant l’opération buildMobileSdkUrlWithCredentials du Transaction Service. L’URL retournée ne contiendra pas le mode de paiement sélectionné. Celui-ci doit être ajouté en annexant le paramètre d’URL paymentMethodConfigurationId avec l’ID de la configuration de mode de paiement à utiliser. L’URL doit être invoquée au sein d’une WebView.

  4. Dès que l’utilisateur indique vouloir finaliser le paiement (par exemple en appuyant sur un bouton continue), la validation doit être déclenchée. Pour cela, le MobileSdkHandler doit être invoqué. Le résultat de la validation devrait ensuite être utilisé pour donner un retour approprié à l’utilisateur. Dans ce cas, nous déclenchons le callback validationCallback.

  5. Dès que le paiement doit être traité (par exemple lorsque l’utilisateur a appuyé sur le bouton pay), le formulaire au sein de la WebView doit être soumis. Cela peut se faire en invoquant la méthode submit du MobileSdkHandler. Une fois le formulaire soumis, il se peut que nous invoquions un service externe (par exemple 3-D secure). Ce service peut nécessiter l’écran entier. Une fois le paiement finalisé, nous invoquons l’un des callbacks suivants : awaitingFinalResultCallback, successCallback ou failureCallback

Diagramme de séquence du Mobile SDK
Figure 1. Diagramme de séquence du flux Mobile SDK

4Action primaire remplacée

Certains modes de paiement nécessitent un processus plus complexe en plusieurs étapes. Par défaut, un bouton est inclus dans le formulaire de paiement pour naviguer à travers ces étapes. Il est toutefois possible de masquer ces boutons et d’utiliser le bouton de soumission primaire de votre application pour déclencher les événements.

Chaque fois que l’action primaire est remplacée, un callback replacePrimaryAction est invoqué avec, en paramètre, le nouveau libellé avec lequel le bouton primaire doit être mis à jour. De plus, le bouton doit être modifié pour déclencher l’action MobileSdkHandler.trigger().

Lorsque le client a parcouru avec succès toutes les étapes nécessaires, le callback resetPrimaryAction est invoqué, ce qui devrait entraîner la réinitialisation du bouton primaire à son comportement par défaut, c’est-à-dire avoir le libellé initial et déclencher les actions MobileSdkHandler.validate(); et MobileSdkHandler.submit();.

Pour masquer les boutons dans le formulaire de paiement, ajoutez le paramètre d’URL replace-primary-action=1 à l’URL de paiement.

5Callbacks

Les callbacks sont déclenchés pour permettre à l’application mobile de réagir à ces événements. Un callback est déclenché par l’invocation d’une URL préfixée par https://localhost/mobile-sdk-callback/. L’URL contient un nom pour le callback et, éventuellement, des données jointes. Exemple : https://localhost/mobile-sdk-callback/some-callback?data={"data":"object"}

La WebView doit être surveillée pour détecter les URL invoquées qui commencent par https://localhost/mobile-sdk-callback/. Ces URL représentent des callbacks.

5.1Initialisation

Lorsque la fenêtre a été entièrement chargée et que tous les écouteurs ont été attachés, le callback initializeCallback est invoqué. Aucune donnée supplémentaire n’est fournie.

5.2Changement de la hauteur du cadre

Lorsque la hauteur du cadre change, le callback heightChangeCallback est invoqué avec la hauteur (en px) dans le paramètre de données.

5.3Remplacement de l’action primaire

Si l’action primaire du formulaire de paiement est remplacée, le callback replacePrimaryAction est invoqué avec le libellé de l’action en paramètre. Le bouton de soumission de votre application doit être mis à jour avec le libellé transmis et doit déclencher l’action trigger lorsqu’il est pressé.

5.4Réinitialisation de l’action primaire

Si l’action primaire du formulaire de paiement a été remplacée puis est réinitialisée au comportement par défaut, le callback resetPrimaryAction est invoqué. Le libellé du bouton de soumission doit être restauré à sa valeur initiale et l’action submit doit être déclenchée lorsqu’il est pressé.

5.5Validation

Lorsque la validation est déclenchée, son résultat est communiqué via le callback validationCallback. Le paramètre de données contient un objet de résultat :

{
	success: false,
	errors: [
		'Message 1',
		'Message 2'
	]
}

5.6En attente du statut final

Lorsque le processus de paiement est terminé, il peut arriver qu’aucun résultat final (succès / échec) ne soit disponible. Dans ce cas, nous invoquons le callback awaitingFinalResultCallback. Le paramètre de données contient l’ID de la transaction. Normalement, un état final de succès ou d’échec est atteint en quelques secondes. Cela peut parfois prendre aussi quelques minutes.

5.7Succès

Lorsque le processus de paiement se termine avec succès, le callback successCallback est invoqué. Le paramètre de données contient l’ID de la transaction. En cas de succès, la transaction est au moins authorized.

5.8Échec

Lorsque le processus de paiement échoue, le callback failureCallback est invoqué. Le paramètre de données contient l’ID de la transaction. Échec signifie que la transaction se trouve dans l’état failed.

6API JavaScript 

<script>

// This triggers the validation.
MobileSdkHandler.validate();

// This triggers the primary action if it has been replaced by the 'replacePrimaryAction' callback.
MobileSdkHandler.trigger();

// This will submit the form and triggers the processing of the payment.
MobileSdkHandler.submit();

</script>

7Tokenisation

Les tokens disponibles peuvent être récupérés avec l’opération fetchOneClickTokensWithCredentials du Transaction Service. Le traitement d’une transaction avec un tel token peut être effectué en utilisant processOneClickTokenWithCredentials. La suppression d’un token peut être exécutée avec l’opération deleteOneClickTokenWithCredentials.

D’autres opérations peuvent être effectuées via les services réguliers Token Service et Token Version Service.

Staging 2.218.1