- Directives d'intégration
- Mise en œuvre d'une intégration Hosted Payment Form
- Le modèle Hosted Payment Form POST
Le modèle Hosted Payment Form POST
Ce modèle Hosted Payment Form nécessite la création d'un code d'intégration côté serveur pour obtenir un jeton de session de American Express Payment Gateway afin d'utiliser l'identifiant de jeton de session renvoyé pour créer le formulaire requis pour l'affichage de la page de paiement et l'analyse de la réponse du formulaire de American Express Payment Gateway.
Bonnes pratiques et conseils
Hosted Payment Form renvoie toujours le champ « gatewayFormResponse », qu'il ait été inclus ou non en tant que champ de publication de formulaire. Certains frameworks Web peuvent générer des erreurs ou restreindre l'accès à ce champ dans ce scénario. Si vous utilisez un framework Web qui exige que les champs de publication du formulaire correspondent à ceux du formulaire initialement présenté, vous devez vous assurer que ce champ est inclus dans le formulaire.
N'incluez pas l'identifiant de session comme champ masqué lorsque vous créez le formulaire de paiement. Ce champ ne doit être inclus que dans l'URL du formulaire. Si vous souhaitez le stocker sur d'autres pages à des fins de référence, il est alors plus approprié de le stocker dans une session HTTP.
La limitation de la longueur des champs de saisie des formulaires est considérée comme une bonne pratique et contribue à maintenir l'intégrité des données. Dans certains cas, les données soumises peuvent être tronquées par Hosted Payment Form si les longueurs de champs ne sont pas limitées.
Les noms de champs peuvent être préfixés mais doivent se terminer par des noms de champs reconnus tels que définis dans la rubrique Référence des champs de formulaire. Par exemple, « ctl00$MainContent$gatewayCardNumber » est un nom de champ valide et sera traité exactement de la même manière qu'un champ nommé « gatewayCardNumber ». Ceci est particulièrement bénéfique pour les intégrateurs utilisant une plateforme .Net.
Les sessions HTTP (à ne pas confondre avec les sessions de paiement) sont souvent utilisées pour assurer le suivi des données du payeur, par exemple les informations sur son panier d'achat, pendant l'interaction du payeur avec le site Web.
L'approche la plus courante pour maintenir les sessions est l'utilisation de cookies. N'oubliez pas que si les témoins ne sont pas activés dans le navigateur du payeur (ou sur votre navigateur Web), vous devrez peut-être également prendre en charge la réécriture d'URL pour conserver la session HTTP dans un témoin. Voir la documentation du framework Web de votre choix pour plus de détails.
Pour vous assurer que Hosted Payment Form gère correctement les caractères codés dans un jeu de caractères différent de celui par défaut (ISO-8859-1), vous devez spécifier un paramètre de requête « charset » dans l'URL du formulaire. Par exemple, pour indiquer que le formulaire soumis est codé avec le jeu de caractères UTF-8, l'URL du formulaire ressemblerait à l'exemple ci-dessous :
https://gateway-emea.americanexpress.com/form/<formSessionIdentifier>?charset=UTF-8
Cela garantit également un codage correct de la réponse. Les jeux de caractères pris en charge se trouvent ici.
Gérez les navigateurs sur lesquels JavaScript est désactivé en personnalisant la page « Continuer ». Lorsque JavaScript est désactivé sur un navigateur, le payeur voit s'afficher une page qui lui demande de cliquer sur un bouton afin d'être redirigé vers votre site. Les attributs suivants de cette page sont personnalisables :
- Le titre de la page peut être personnalisé/localisé en spécifiant une valeur pour le champ « gatewayRedirectDisplayTitle ».
- Le texte du bouton peut être personnalisé/internationalisé en spécifiant une valeur pour le champ « gatewayRedirectDisplayContinueButtonText ».
- La couleur d'arrière-plan peut être personnalisée en spécifiant une valeur pour le champ « gatewayRedirectDisplayBackgroundColor ».
Si aucune valeur n'est fournie, des valeurs par défaut s'appliquent
Bien que cela ne soit pas strictement obligatoire pour l'intégration à la solution Hosted Payment Form, les informations du payeur étant envoyées à Hosted Payment Form sous SSL, ce dernier procure les avantages suivants :
-
Il accroît la confiance du payeur en affichant le verrou du navigateur
-
Il évite que le payeur ne voie la fenêtre contextuelle d'avertissement de sécurité lorsqu'il revient du site sécurisé Hosted Payment Form à votre site non sécurisé. La fenêtre contextuelle d'avertissement de sécurité demande au payeur s'il souhaite continuer à envoyer les informations.
Flux d'informations Hosted Payment Form
Le flux de paiement détaillé pour le modèle Hosted Payment Form est illustré ci-dessous.
- Vous lancez un appel American Express Payment GatewayWeb-Services API à American Express Payment Gateway via l'opération
Create Session (Créer une session). Cela crée la session, qui conservera les détails de la carte du payeur. Voir Demande d'une session via Web-Services API. - American Express Payment Gateway répond avec l'identifiant de session.
- Votre site crée la page de paiement qui inclut le formulaire de paiement.
- Le formulaire de paiement doit inclure les champs pris en charge par le service Hosted Payment Form de American Express Payment Gateway que vous devez collecter auprès du payeur.
- Il peut également contenir des champs supplémentaires que vous souhaiterez peut-être collecter à ce stade. par exemple : Adresse d'expédition, Numéro de bon de réduction, etc.,
- Le formulaire de paiement peut être conçu selon vos besoins.
Voir Création d'un formulaire de paiement et Références des champs de formulaire de paiement.
- Le formulaire de paiement s'affiche pour le payeur, en attente de la saisie des détails de la carte et des autres informations requises.
Ce formulaire sert uniquement à collecter les détails de la carte et non à effectuer un paiement.
- Le payeur saisit les détails de cette dernière et clique sur le bouton « Soumettre » de votre site Web, ce qui entraîne une opération HTTPS POST vers le service de Hosted Payment Form. Vous devez intégrer l'identifiant de session dans le champ d'action de votre formulaire. Voir Création d'un formulaire de paiement.
- American Express Payment Gateway collecte, vérifie (à l'aide de la vérification de base) et nettoie les détails de la carte, puis renvoie le formulaire validé/modifié au navigateur. Les détails de la carte tels que le numéro de carte, l'expiration de la carte et les données CSC/CVV sont extraits du formulaire et ajoutés à la session.
- Le formulaire validé vous est envoyé à partir du navigateur du payeur au moyen de l'URL de retour spécifiée dans la demande Soumettre un formulaire. Le formulaire validé comprend les champs de demande et les champs de réponse du service Hosted Payment Form de American Express Payment Gateway.
Les champs spécifiques au commerçant que vous pouvez transmettre dans la demande de formulaire sont renvoyés sans aucun traitement dans la réponse du formulaire.
- Votre site valide les champs spécifiques au commerçant.
- Votre site analyse toutes les erreurs renvoyées par le service Hosted Payment Form de American Express Payment Gateway et réaffiche la page de paiement en cas de détection d'erreurs.
Lorsque toutes les erreurs ont été corrigées, vous pouvez choisir d'afficher d'autres pages pour le payeur en fonction du flux de travail de votre entreprise ou d'effectuer une transaction de stockage ou de paiement au moment de la collecte des détails de la carte.
Avant d'effectuer la transaction de paiement, vous pouvez soumettre une demande d'évaluation du taux pour la conversion de devise dynamique (DCC) afin d'extraire la devise du payeur et le montant de la commande dans cette devise.
À ce stade, vous pouvez également authentifier le payeur au moyen du service 3-D Secure. Notez que si le payeur accepte l'offre DCC, vous devez fournir les informations DCC dans la demande d'authentification. - Vous effectuez un appel American Express Payment GatewayWeb-Services APIpour lancer la transaction de paiement ou de stockage en spécifiant le montant du paiement (uniquement pour une transaction de paiement) à l'aide d'un ou plusieurs des éléments suivants : Authorize (Autoriser), Pay (Payer), Tokenization (Segmentation en jetons). Les détails de carte peuvent être fournis à l'aide de sources multiples de détails de cartes. Pour plus d'informations, voir Exécution d'une opération au moyen de la session.
- American Express Payment Gateway vous renvoie le résultat de la transaction. Vous pouvez effectuer une transaction Save (Enregistrer) après une transaction Pay/Authorize (Payer/Autoriser) avant l'expiration de la session.
Dépannage et questions fréquentes
Le formulaire de paiement peut renvoyer différents types d'erreurs. Voir Gestion des erreurs.
Une page d'erreur s'affiche lors d'une tentative de soumission de formulaire incorrecte. Les cas suivants entraîneront l'affichage d'une page d'erreur :
- La méthode du formulaire n'est pas HTTP POST.
- L'URL du formulaire n'est pas correctement formatée.
- Un paramètre de requête autre que « charset » est transmis dans l'URL du formulaire.
- Un jeu de caractères non pris en charge est transmis en tant que paramètre de requête dans l'URL du formulaire.
- Le champ obligatoire « gatewayReturnURL » n'a pas été renseigné.
- Le champ obligatoire « gatewayReturnURL » n'est pas une URL absolue.
- Les noms de champs réservés sont utilisés dans le formulaire de paiement. Le seul nom de champ réservé est actuellement « submit » (respecte la casse), qui ne doit pas être défini comme attribut name du bouton.
- Un champ reconnu a été soumis avec plusieurs valeurs. Cela se produit généralement lorsque le champ est défini plusieurs fois dans le formulaire.
Le fait d'avoir un champ dont l'attribut « name » a la valeur « submit » empêche la redirection du formulaire vers votre site via le transfert JavaScript. En effet, ce transfert via JavaScript s'opère au moyen de la fonction form.submit(). Ainsi, s'il existe un élément du formulaire nommé « submit », JavaScript référence le champ de manière incorrecte au lieu d'exécuter la fonction. Il s'agit d'un problème JavaScript bien connu qu'il n'est pas facile de contourner.
Les champs définis par le commerçant sont renvoyés dans la réponse du formulaire sans être traités ni enregistrés par Hosted Payment Form.
Cela est dû au fait que le navigateur doit afficher une page HTML avant d'exécuter le code JavaScript de publication sur votre site. Le scintillement se produit très brièvement lors de l'affichage de cette page avant l'exécution du code JavaScript. Pour garantir que le payeur bénéficie d'une expérience transparente, il est conseillé d'affecter aux attributs personnalisables de la page « Continuer » des valeurs qui préservent l'apparence de votre site. Voir Bonnes pratiques et conseils pour plus de détails sur la manière de personnaliser la page « Continuer ». Cela garantit également que les payeurs qui n'ont pas un navigateur avec JavaScript activé voient s'afficher une page « Continuer » cohérente avec l'apparence de votre site.