Intégration Hosted Session Click to Pay
Suivez les étapes ci-dessous pour ajouter Click to Pay (C2P) à votre intégration Hosted Session à l'aide du SDK Click to Pay et de l'API JavaScript (JS). Vous trouverz un exemple HTML d'intégration de base à la fin de cette rubrique.
Pour plus d'informations sur l'option C2P, les tests de l'intégration complète et certaines questions fréquentes, voir Click to Pay.
Étape 1 : Créer et mettre à jour une session
Créez une session à l'aide de l'opération CREATE SESSION (Créer une session). La réponse renvoie un ID de session que vous devez utiliser dans les étapes suivantes pour référencer la session.
Vous pouvez ajouter ou mettre à jour des champs dans une session existante à l'aide de l'opération UPDATE SESSION (Mettre à jour la session). Les champs suivants doivent au moins être renseignés dans une session :
session.id
Identifiant de la session de paiement.order.amount
Montant total de la commande.order.currency
Devise de la commande.
CREATE SESSION (Créer une session) et UPDATE SESSION (Mettre à jour la session) sont des opérations d'API côté serveur qui constituent une condition préalable à l'intégration à l'API JS. Utilisez la version 62 de l'API WS ou une version supérieure avec l'API JS.
Pour des exemples de demandes d'opérations d'API côté serveur, téléchargez la collection Postman.
Étape 2 : Inclure le API JavaScript Click to Pay sur votre page de paiement
Incluez le SDK JavaScript C2P (click-to-pay.js) fourni par Mastercard Gateway sur votre page de paiement en ajoutant un élément de script dans l'élément head de votre code HTML. Cela place un objet ClickToPay dans l'espace de noms de la fenêtre.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/static/click-to-pay/click-to-pay.min.js"></script>
Étape 3 : Configurer l'interaction Click to Pay
L'objet de configuration permet de configurer l'interaction entre le payeur et C2P sur votre page de paiement. Lorsque le payeur est prêt à régler sa commande et que vous chargez votre page de paiement, lancez l'interaction C2P en appelant la fonction ClickToPay.configure(). Pour plus d'informations et un exemple de la fonction, voir Référence de l'API.
L'initialisation de la bibliothèque C2P peut prendre quelques secondes. Initialisez les composants le plus tôt possible lors du chargement de la page afin que le payeur puisse payer rapidement via C2P.
Dans la fonction ClickToPay.configure(), configurez les paramètres, les composants de la page de paiement et les rappels pour l'interaction C2P, comme définis dans les sections suivantes.
Paramètres de configuration
Utilisez les paramètres pour définir les détails de votre interaction C2P.
Tableau : Paramètres de configuration
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
merchant.id |
Oui | Chaîne | Votre ID de commerçant, utilisé par la passerelle pour déterminer vos options de paiement. |
merchant.name |
Oui | Chaîne | Votre nom commercial, par exemple, le nom connu de votre payeur. |
merchant.url |
Obligatoire | Chaîne d'URL | URL de votre site Web utilisée par le payeur. |
session.id |
Oui | Chaîne | ID de session renvoyé par l'opération CREATE SESSION (Créer une session) à l'étape 1. |
session.wsVersion |
Oui | Entier | Version de l'API WS utilisée lors de la soumission de l'opération CREATE SESSION (Créer une session) à l'étape 1. La valeur doit être >= 62. |
order.amount |
Oui | Chaîne | Montant de la commande. La valeur est utilisée uniquement à des fins d'affichage et non pour le traitement du paiement. |
order.currency |
Oui | Chaîne | Devise de la commande. La valeur est utilisée uniquement à des fins d'affichage et non pour le traitement du paiement. |
interaction.billingPreference |
Non | Chaîne d'énumération | Si une adresse de facturation est collectée au cours de l'interaction C2P. Les valeurs possibles sont les suivantes :
|
interation.collectShippingAddress |
Non | Booléen | Si une adresse d'expédition est collectée au cours de l'interaction C2P. La valeur par défaut est false. Par défaut, le payeur peut sélectionner n'importe quel pays pour l'adresse d'expédition. Pour limiter la liste aux pays vers lesquels vous expédiez des marchandises, vous devez configurer votre profil de commerçant pour l'option C2P via Merchant Administration (MA) avec une liste de pays autorisés ou une liste de pays exclus. Si vous avez défini des restrictions, le payeur ne peut sélectionner qu'un pays d'adresse d'expédition autorisé. Vous ne pouvez pas remplacer les pays d'adresse d'expédition pris en charge pour une demande spécifique, uniquement pour toutes les demandes de votre profil de commerçant. |
interation.locale |
Non | Chaîne | Langue utilisée lors de l'interaction C2P. Par défaut, la langue configurée dans le navigateur du payeur est utilisée. Si la langue du payeur ne peut pas être déterminée ou n'est pas prise en charge, la valeur en_US est utilisée, sauf si vous indiquez une valeur différente dans ce paramètre.
|
interation.country |
Non | Chaîne | Contenu spécifique au pays, tel que les conditions générales, présenté au payeur lors de l'interaction C2P. La valeur que vous avez configurée par rapport à votre profil de commerçant sur la passerelle est utilisée par défaut. Si vous souhaitez remplacer cette valeur pour cette interaction, définissez ce paramètre sur une valeur de pays ISO 3166 alpha-3 valide. |
interaction.cardSelectionAction |
Non | Chaîne | Action à effectuer lorsque le payeur sélectionne la carte. Les valeurs possibles sont les suivantes :
|
interaction.skipDCFInteraction |
Non | Booléen | Indique si le payeur doit confirmer manuellement son adresse électronique et son numéro de téléphone. Pour l'instant, cela s'applique uniquement à l'inscription à la carte Mastercard. Les paramètres customer.email et customer.mobilePhone sont obligatoires dans la fonction configure() pour que cette fonctionnalité prenne effet.Si la valeur est true, le payeur ne reçoit pas de message Confirmer sur le composant DCF (interface utilisateur du facilitateur de carte numérique) et un bref écran de chargement s'affiche. Si elle n'est pas indiquée, la valeur par défaut est false. |
customer.email |
Oui | Chaîne | E-mail du payeur. L'option C2P utilise la valeur pour rechercher le profil du payeur dans le système SRC (Secure Remote Commerce). La recherche d'e-mail n'est lancée que si l'appareil n'est pas reconnu. Si l'appareil est reconnu, ce champ est ignoré. Incluez sur votre site des informations indiquant que l'adresse électronique du payeur est utilisée à des fins de recherche, sauf si vous avez déjà informé le payeur que son adresse électronique est utilisée pour rechercher son profil C2P. Vous pouvez inclure un avis informant que vous avez conclu un partenariat avec des systèmes de cartes participants afin de proposer un service C2P pour un paiement plus rapide et que l'adresse électronique du payeur est partagée en toute sécurité avec les systèmes de cartes participants afin de vérifier si celui-ci dispose déjà d'un profil C2P. |
customer.mobilePhone |
Non | Numéro de téléphone | Numéro de téléphone portable ou cellulaire du payeur au format ITU-T E123, par exemple +1 607 1234 5678. Le numéro est composé :
|
customer.firstName |
Non | Chaîne | Prénom du payeur. |
customer.lastName |
Non | Chaîne | Nom de famille du payeur. |
srcDCFCancel |
Oui (uniquement si vous prévoyez de prendre en charge les cartes Visa) | - | La conception actuelle de Visa pour l'option C2P ferme sa session C2P si le payeur sélectionne le « X » affiché dans le coin supérieur droit du composant Visa DCF. Lorsque cet événement est envoyé, il est recommandé de réinitialiser l'option C2P (appeler la fonction configure()) pour garantir des sessions ouvertes pour tous les systèmes de cartes. |
Composants de la page de paiement
L'option C2P fournit plusieurs composants qui peuvent être intégrés à votre page de paiement pour améliorer l'interaction C2P. Créez des éléments div à l'emplacement de votre page de paiement où vous souhaitez que ces composants soient affichés et identifiez les éléments div dans la rubrique éléments de l'objet de configuration.
Tableau : Composants de page de paiement disponibles
| Champ | Obligatoire | Description |
|---|---|---|
cardList |
Oui | ID de l'élément DOM où le composant Liste de cartes est affiché. |
otp |
Non | ID de l'élément DOM où le composant de mot de passe à usage unique est affiché. S'il n'est pas fourni, le mot de passe à usage unique est affiché en superposition. |
dcf |
Oui | ID de l'élément DOM où le composant DCF est affiché. S'il n'est pas fourni, le composant DCF est affiché en superposition. |
Rappels
Vous devez définir les actions à appeler au cours de l'interaction C2P en tant que rappels.
Rappel onStateChange
Le flux initial est déterminé après avoir appelé la fonctionconfigure() :
- Si un cookie C2P valide est détecté, le flux « Utilisateur reconnu par cookie » est utilisé et le composant de liste de cartes est affiché.
- Si un e-mail C2P valide est détecté, le flux « Utilisateur reconnu par e-mail » est utilisé et le payeur est invité à fournir un mot de passe à usage unique avant que le composant de liste de cartes ne soit affiché.
- Si aucun cookie ou e-mail valide n'est détecté, le flux « Nouvel utilisateur » est utilisé.
Le rappel onStateChange est déclenché lorsque le statut de l'interaction C2P change. Vous pouvez l'utiliser pour déterminer quels composants sont visibles et à quelle étape se trouve le payeur dans le flux.
Exemple d'objet de rappel onStateChange
oldState : {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email if not supplied in customer.email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: true},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: false}
}
},
newState: {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: false},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: true}
}
},
diffState: {
elementState: {
dcf: {selector:'dcfContainer', visible: true}
}
}
Le tableau suivant fournit des exemples de gestion des changements d'état avec les différents flux.
Tableau : Changements d'états
| État | Valeur du champ Ancien état | Valeur du champ Nouvel état | Commentaires |
|---|---|---|---|
| Chargement de la page (avant l'affichage de la liste des cartes) après l'affichage de isRecognized et avant l'affichage de cardList | {} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
- |
| Après avoir cliqué sur la carte et avant de rediriger vers le DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| Une fois le paiement terminé | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
Le rappel onComplete retourne correlationId, scheme, digitalCardId. Passer à l'étape 6 |
Flux Utilisateur reconnu par cookie
| État | Valeur du champ Ancien état | Valeur du champ Nouvel état | Commentaires |
|---|---|---|---|
Chargement de la page après isRecognized() et avant l'affichage de la liste des cartes |
{} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| Après avoir cliqué sur une carte et avant la redirection vers le composant DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Une fois le paiement terminé | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Le rappel onComplete renvoie l'ID de corrélation, le système et l'ID de carte numérique. Continuez à partir de l'étape 6. |
| Après la saisie d'un mot de passe à usage unique valide | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: true},
dcf: {selector:'#dcfContainer', visible: false}
}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| Après avoir cliqué sur une carte et avant la redirection vers le composant DCF | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Une fois le paiement terminé | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Le rappel onComplete renvoie l'ID de corrélation, le système et l'ID de carte numérique. Continuez à partir de l'étape 6. |
| Chargement de page avec e-mail | {
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Le profil C2P du payeur n'étant pas reconnu, vous pouvez afficher les champs de saisie de la carte, recueillir les détails du payeur et mettre à jour la session. L'e-mail est vide; s'il n'est pas indiqué dans les paramètres de configuration. |
Appeler la fonction checkoutWithNewCard() avant que le composant DCF ne soit affiché |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Une fois le paiement terminé | {
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Le rappel onComplete renvoie l'ID de corrélation, le système et l'ID de carte numérique. Continuez à partir de l'étape 6. |
Rappel onComplete
Le rappel onComplete est déclenché lorsque le payeur a terminé l'interaction avec le composant DCF.
Cette fonction utilise deux arguments :
scheme: Système de cartes- correlationId : identifiant unique de l'interaction C2P (pour ce système)
Ces informations doivent être utilisées à l'étape 6 pour récupérer les informations de paiement pour cette interaction C2P.
Rappel onError
=rappel onError renvoie un objet d'erreur si une erreur se produit lors de l'interaction C2P. Il contient deux champs :
{
errorCode: 'INVALID_INPUT',
errorMessage: 'session id is required'
}
Tableau : Codes d'erreur d'intégration
| Code d'erreur | Message d'erreur | Votre action |
|---|---|---|
CALLBACKS_ONCOMPLETE_ERROR |
Argument manquant : rappel onComplete requis | Incluez la fonction de rappel onComplete dans la fonction configure(). |
CALLBACKS_ONERROR_ERROR |
Argument manquant : rappel onError requis | Incluez la méthode de rappel onError dans la fonction configure(). |
MERCHANT_ID_ERROR |
Argument manquant : ID du commerçant requis | Incluez le champ merchant.id dans la fonction configure(). |
MERCHANT_NAME_ERROR |
Argument manquant : nom du commerçant requis | Incluez le champ merchant.name dans la fonction configure(). |
MERCHANT_URL_ERROR |
Argument manquant : URL du commerçant requise | Incluez le champ merchant.url dans la fonction configure(). |
SESSION_ID_ERROR |
Argument manquant : ID de session requis | Incluez le champ session.id dans la fonction configure(). |
MISSING_API_VERSION_ERROR |
Argument manquant : Version de l'API requise | Incluez le champ wsVersion dans la fonction configure(). |
ORDER_AMOUNT_ERROR |
Argument manquant : Montant de la commande requis | Incluez le champ order.amount dans la fonction configure(). |
ORDER_CURRENCY_ERROR |
Argument manquant : Devise de la commande requise | Incluez le champ order.currency dans la fonction configure(). |
MIN_API_VERSION_ERROR |
La version de l'API doit être supérieure ou égale à 62 | Modifiez la valeur du champ wsVersion sur au moins 62 ; toutes les opérations doivent être effectuées à l'aide de 62 ou une valeur supérieure. |
CARD_LIST_ERROR |
Argument manquant : elements.cardList requis | Incluez le champ elements.cardList qui renvoie au composant div de la liste de cartes. |
DCF_ERROR |
Argument manquant : elements.dcf requis | Incluez le champ elements.dcf qui renvoie au composant div de la liste de cartes. |
MISSING_EMAIL_ERROR |
Argument manquant : e-mail requis | Incluez le champ customer.email dans la fonction configure(). |
CUSTOMER_EMAIL_ERROR |
Erreur de format de l'e-mail client | Assurez-vous que seules les adresses électroniques de payeur valides sont acceptées par votre site. |
INTERACTION_LOCALE_ERROR |
Erreur de format des paramètres régionaux de l'interaction | Indiquez un paramètre régional valide en utilisant le format <language>_<country>, tel que fr_FR. |
INTERACTION_COUNTRY_ERROR |
Erreur de format du pays de l'interaction | Fournissez une valeur de pays ISO 3166 alpha-3 valide dans le champ interaction.country. |
Tableau : Codes d'erreur de paiement
| Code d'erreur | Message d'erreur | Action requise |
|---|---|---|
CARD_MISSING |
ID de carte numérique ou objet de carte cryptée requis, mais manquant | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
CARD_ADD_FAILED |
Impossible d'ajouter la carte lors de l'exécution du flux combiné. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
CARD_SECURITY_CODE_MISSING |
Le code sécurité de la carte doit être indiqué lors de l'exécution du flux combiné. | Assurez-vous que le champ cardSecurityCode dans la fonction ClickToPay.checkoutWithNewCard() contient une valeur à 3 chiffres (ou 4 chiffres pour Amex). |
CARD_INVALID |
Numéro de carte non valide lors de l'exécution du flux combiné. | Assurez-vous que le champ primaryAccountNumber dans la fonction ClickToPay.checkoutWithNewCard() correspond à une carte valide. |
CARD_NOT_RECOGNIZED |
La carte spécifiée n'a pas été reconnue. | Assurez-vous que le champ primaryAccountNumber dans la fonction ClickToPay.checkoutWithNewCard() correspond à une carte valide. |
CARD_EXP_INVALID |
Date d'expiration de la carte non valide. | Assurez-vous que les champs panExpirationYear et panExpirationMonth dans la fonction ClickToPay.checkoutWithNewCard() sont valides. |
MERCHANT_DATA_INVALID |
Données du commerçant non valides. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
UNABLE_TO_CONNECT |
Connexion/lancement du DCF impossible. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
AUTH_INVALID |
Jeton d'ID fédéré non valide. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
Codes d'erreur C2P standard
| Code d'erreur | Message d'erreur | Action requise |
|---|---|---|
REQUEST_TIMEOUT |
La demande a pris plus de temps que le temps autorisé pour se terminer. Cela peut signifier que le service connaît un volume élevé d'appels. Réessayez plus tard. Cela peut également être dû au fait que le SDK n'arrive pas à communiquer avec son iFrame. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
SERVER_ERROR |
Indique que le serveur a rencontré une condition inattendue qui l'a empêché de répondre à la demande. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
INVALID_PARAMETER |
La valeur indiquée pour un ou plusieurs paramètres de demande est considérée comme non valide. Cette erreur est également générée lorsqu'un champ obligatoire est manquant. Remarque : dans la mesure du possible, vous devez fournir une validation côté client pour éviter un aller-retour inutile vers le serveur. Les contraintes de validation simples sont documentées dans le cadre de la spécification de l'API. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
INVALID_REQUEST |
Le serveur n'a pas pu comprendre la demande. Cela signifie généralement qu'un champ de données doit être dans un format particulier, mais ne l'est pas. Par exemple, le décodage base64 peut avoir échoué. Le champ de message peut fournir des indications supplémentaires sur la partie/le champ de la demande considéré(e) comme incorrect(e). | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
AUTH_ERROR |
Le serveur comprend la demande, mais ne peut pas s'authentifier. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
NOT_FOUND |
La ressource/l'entité commerciale demandée n'existe pas. La ressource peut également être masquée pour des raisons de sécurité. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
TERMS_AND_CONDITIONS_NOT_ACCEPTED |
Conditions générales non acceptées. | Revenez au flux de paiement en tant qu'invité. |
IS_CONFIGURED_ERROR |
configure() ne s'est pas terminé. La configuration doit être initialisée en premier. | Assurez-vous que votre intégration a appelé la fonction configure(). Assurez-vous de prévoir suffisamment de temps pour que la fonction se termine avant de rendre visibles les composants C2P. |
SRCI_ID_MISSING |
Identifiant de l'initiateur SRC manquant. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
DPA_ID_MISSING |
Identifiant pour le DPA manquant | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
SRCI_TXID_MISSING |
Identifiant de la transaction de l'initiateur SRC manquant. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
DPA_TXOPT_MISSING |
Structure des options de transaction DPA manquante. | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
INVALID_STATE |
Le compte existe mais n'est pas dans un statut « actif » pour ce programme. | Revenez au flux de paiement en tant qu'invité. |
CONSUMER_ID_MISSING |
Identité du consommateur requise mais non fournie. | Revenez au flux de paiement en tant qu'invité. |
FRAUD |
Compte de l'utilisateur verrouillé ou désactivé. | Revenez au flux de paiement en tant qu'invité. |
ID_FORMAT_UNSUPPORTED |
ID de session non valide | L'option C2P n'est pas disponible, revenez au flux de paiement en tant qu'invité. |
Délai de mot de passe à usage unique pour les utilisateurs reconnus par e-mail (facultatif)
Si le payeur est reconnu par C2P sur la base de son e-mail, le comportement par défaut est d'afficher automatiquement le mot de passe à usage unique fourni par l'option C2P.
Si, pour une raison quelconque, vous souhaitez lancer l'interaction C2P mais supprimer l'affichage du mot de passe à usage unique fourni par l'option C2P jusqu'à une date ultérieure (pendant que vous affichez des écrans supplémentaires au payeur avant qu'il ne continue), ajoutez le champ interaction.suppressPayerInteraction à la fonction ClickToPay.configure().
Si vous définissez le champ interaction.suppressPayerInteraction sur true, la fonction configure() configure l'interaction C2P et vérifie si le payeur est reconnu à l'aide de son email ou d'un cookie ou s'il s'agit d'un nouvel utilisateur. Cependant, la fonction ne déclenche pas l'interaction C2P avec le payeur (n'affiche pas les composants associés).
Si le champ est omis ou défini sur false, la fonction configure() configure l'interaction C2P, vérifie si le payeur est reconnu grâce à son e-mail ou un cookie ou s'il est un nouvel utilisateur et déclenche immédiatement l'interaction C2P avec le payeur.
Si le champ interaction.suppressPayerInteraction est défini sur true, vous devez effectuer les actions suivantes en fonction du statut de reconnaissance du payeur. Si le payeur est :
- Reconnu en fonction de son e-mail (
emailEnrolled = trueetemailVerified = false), l'application du commerçant peut appliquer des étapes supplémentaires dans son flux avant de lancer la vérification du mot de passe à usage unique de l'option C2P. Vous devez ensuite appeler la fonctionClickToPay.initiatePayerInteraction()pour afficher le mot de passe à usage unique au payeur. - Non reconnu en fonction de son e-mail (il s'agit d'un nouvel utilisateur ou il est reconnu grâce à un cookie), l'application du commerçant doit appeler la fonction
initiatePayerInteraction()immédiatement.
Étape 4 : Mettre à jour les changements d'adresse électronique
Si le payeur peut modifier son adresse électronique sur la même page qui affiche les composants C2P, toute modification apportée à l'adresse électronique du payeur doit être transmise au SDK C2P. Chaque fois que le payeur met à jour son adresse électronique, appelez la fonction ClickToPay.lookupCustomer(email) pour mettre à jour le SDK C2P. L'e-mail du payeur est utilisé pour vérifier si ce payeur possède un profil C2P existant associé à son adresse électronique.
Si vous collectez l'adresse électronique du payeur sur votre site, informez le payeur que son adresse électronique est utilisée pour rechercher son profil C2P. Vous pouvez inclure une info-bulle à côté du champ de saisie de l'adresse électronique pour informer le payeur que « vous avez conclu un partenariat avec des systèmes de cartes participants afin de proposer un service C2P pour un paiement plus rapide et que l'adresse électronique du payeur est partagée en toute sécurité avec les systèmes de cartes participants afin de vérifier si celui-ci dispose déjà d'un profil C2P. ».
Si l'adresse électronique mise à jour est :
-
- Liée à un profil C2P existant :
- Le rappel
onStateChangeest déclenché avecnewState.payerState.emailEnrolled = true. - Le formulaire de saisie du mot de passe à usage unique est affiché par le SDK JavaScript C2P.
- Le rappel
- Non liée à un profil C2P existant, le rappel
onStateChangeest déclenché avecnewState.payerState.emailEnrolled = false.
Étape 5 : Implémenter le paiement
Si le payeur décide de payer en utilisant une carte existante de son profil C2P, appelez la fonction ClickToPay.checkoutWithExistingCard() après que le payeur ait sélectionné la carte dans la liste des cartes. La fonction dirige le payeur sur l'écran de confirmation de carte dans le composant DCF.
Si le payeur décide d'inscrire une nouvelle carte dans son profil C2P ou n'a pas de profil :
- Affichez le formulaire de saisie de la carte sous forme de champs Hosted Session afin que le payeur puisse saisir ses détails de paiement et cliquer sur Payer. Vous devez afficher les champs pour les éléments suivants :
- Numéro de carte
- Code de sécurité
- Mois et année d'expiration
- Nom figurant sur la carte
- Récupérez le système de cartes deu Hosted Session à l'aide du rappel
PaymentSession.onCardTypeChange, qui se déclenche lorsque le payeur renseigne le numéro de carte dans le champ hébergé. - Appelez la fonction
ClickToPay.isEnrollmentAvailableForScheme()en utilisant le système.
La fonction vérifie le système fourni par rapport àpaymentTypes.card.walletProviders[n].secureRemoteCommerce.scheme[n].namedans la réponse de l'opération PAYMENT OPTIONS INQUIRY (Demande d'options de paiement) pour déterminer si vous êtes activé pour le système.
Si la fonction renvoiefalse, quittez ce flux et utilisez le flux de paiement invité pour traiter la carte normalement sans l'option C2P. - Afficher et recueillir le consentement :
- Si vous êtes situé aux États-Unis, indiquez que, si le payeur choisit de continuer, vous partagerez les détails de sa carte, son adresse de facturation et son adresse électronique avec les systèmes de cartes participants afin de permettre au payeur de s'inscrire à l'option C2P pour des paiements plus rapides.
- Si vous résidez en dehors des États-Unis, affichez :
- la case de consentement non cochée,
- Le texte de consentement dans lequel le payeur accepte de partager les détails de la carte, l'adresse de facturation et l'adresse électronique avec les systèmes de cartes participants afin de permettre son inscription à l'option C2P pour des paiements plus rapides.
- Lorsque le payeur clique sur le bouton Payer de votre page de paiement pour passer à l'étape suivante :
- Si vous êtes situé en dehors des États-Unis et que la case de consentement n'est pas cochée, le payeur n'a pas consenti à partager des données avec l'option C2P. Suivez le flux de paiement en tant qu'invité et traitez la carte normalement sans l'option C2P.
- Si vous êtes situé aux États-Unis ou en dehors des États-Unis et que l'utilisateur a coché la case de consentement, mettez à jour la session à l'aide de la fonction
PaymentSession.updateSessionFromForm().
Vous pouvez également mettre à jour la session avec une adresse debillingfacultative à l'aide de l'objet de facturation dans une demande UPDATE SESSION (Mettre à jour la session). Si vous insérez les informations de facturation du payeur dans la session de paiement, le payeur n'a pas besoin de les ressaisir lors de l'inscription à l'option C2P.
- Après avoir mis à jour la session, appelez la fonction
ClickToPay.checkoutWithNewCard(), qui dirige le payeur à l'écran d'inscription de la carte dans le composant DCF :
- Si la fonction échoue, le rappel
onErrorest appelé. Prenez les mesures nécessaires pour résoudre l'erreur. - Si la fonction réussit, le payeur est redirigé vers le composant DCF.
- Si la fonction échoue, le rappel
- Le payeur interagit avec le composant DCF pour faciliter l'inscription. Une fois le rappel
onCompleteappelé, l'interaction C2P est terminée et vous pouvez passer à l'étape 6 pour mettre à jour la session avec les détails de l'option C2P.
Étape 6 : Mettre la session à jour avec les détails de paiement de l'option Click to Pay
Vous devez demander à la passerelle de récupérer les détails de paiement pour l'interaction C2P et de les stocker dans la session, une fois que votre payeur a terminé avec succès l'interaction C2P.
Soumettez une demande d'API UPDATE SESSION FROM WALLET (Mettre à jour la session à partir du portefeuille) côté serveur avec :
- ID de session dans l'URL de la demande.
- ID de corrélation et système tels que renvoyés dans le rappel
onComplete.
| Exemple de demande UPDATE SESSION FROM WALLET (Mettre à jour la session à partir du portefeuille) |
|---|
URL: "https://ap-gateway.mastercard.com/form/version/<version>/merchant/<merchant_ID>/session/<session_ID>
HTTP Method POST
{
"apiOperation":"UPDATE_SESSION_FROM_WALLET",
"order":{
"walletProvider":"SECURE_REMOTE_COMMERCE"
},
"wallet":{
"secureRemoteCommerce":{
"srcCorrelationId":"<correlationId_provided_in_payloadCallback>,
"scheme":"<scheme_provided_in_payloadCallback>"
}
}
}
|
Si la session est mise à jour avec succès avec les détails de paiement issus de l'interaction C2P, affichez un écran de confirmation de paiement pour confirmer que tous les détails sont corrects avant que le payeur ne s'engage sur le paiement. Si la session n'a pas été mise à jour avec succès, demandez à votre payeur de sélectionner une autre option de paiement.
Étape 7 : Exécuter une authentification 3-D Secure (facultatif)
Si vous souhaitez authentifier le payeur, effectuez une authentification 3-D Secure en utilisant la session. Pour des instructions détaillées, voir 3DS avec l'API JavaScript 3DS.
Étape 8 : Exécuter l'opération de paiement
En raison d'une limitation de la fonctionnalité DCF de Visa, si le payeur choisit de revenir à la page de saisie/de sélection de carte d'origine pour utiliser une carte différente pour le paiement après avoir terminé la partie DCF du flux, vous devez réinitialiser le SDK. L'approche recommandée consiste à appeler à nouveau la fonction configure().
Une fois que le payeur s'est engagé à effectuer le paiement (et que l'authentification 3-D Secure a réussi, le cas échéant), utilisez la session pour soumettre le paiement au traitement de votre serveur. Par exemple, vous pouvez soumettre une demande AUTHORIZE (Autoriser).
Les détails de paiement stockés dans la session à partir de l'interaction C2P sont utilisés pour traiter le paiement. Vous pouvez utiliser la même session pour plusieurs opérations d'API. Pour plus d'informations sur les demandes de paiement au cours d'une session, voir Principes de base des sessions.
Pour les flux de paiement en tant qu'invité, utilisez l'Hosted Session implémentation de base pour recueillir les détails de la carte à partir des champs hébergés et les ajouter à la session avant d'envoyer l'opération de paiement.
| Exemple de demande AUTHORIZE (Autoriser) |
|---|
URL: "https://ap-gateway.mastercard.com/form/version/{version}//merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID>
HTTP Method PUT
{
"apiOperation":"AUTHORIZE",
"session": {
"id": "<session_ID>"
}
}
|
Exemple HTML pour l'intégration
Cette rubrique décrit une intégration simple permettant à Hosted Session de collecter les détails de la carte de crédit du payeur et de configurer l'option C2P.
Hosted SessionExemple d'intégration
Exemple
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://ap-gateway.mastercard.com/form/version/<Version>/merchant/<Merchant ID>/session.js"></script>
<!-- INCLUDE CLICK-TO-PAY.MIN.JS JAVASCRIPT LIBRARY -->
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/static/click-to-pay/click-to-pay.min.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>
<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
<div>Please enter your payment details:</div>
<h3>Credit Card</h3>
<div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div>
<div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two-digit expiry month" value="" tabindex="2" readonly></div>
<div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two-digit expiry year" value="" tabindex="3" readonly></div>
<div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three-digit CCV security code" value="" tabindex="4" readonly></div>
<div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div>
<div><button id="payButton" onclick="pay('card');">Pay Now</button></div>
<!-- CREATE THE HTML FOR THE CLICK-TO-PAY INTERACTION -->
<div>C2P Fields Below------</div>
Email: <input id="payerEmail" onblur="updateEmail();" /><br/>
<div id="cardListContainer" ></div><br/>
<div id="otpContainer"></div><br/>
<div id="cardFacilitator" ></div><br/>
<div id="coid" ></div><br/>
<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
PaymentSession.configure({
session: "<your_session_ID>",
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD
card: {
number: "#card-number",
securityCode: "#security-code",
expiryMonth: "#expiry-month",
expiryYear: "#expiry-year",
nameOnCard: "#cardholder-name"
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
console.log('initialized: ' + response)
if(response.status === 'ok') {
//configure C2P
configure()
}
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
//CHECK IF SECURITY CODE WAS PROVIDED BY THE USER
if (response.sourceOfFunds.provided.card.securityCode) {
console.log("Security code was provided.");
}
//CHECK IF THE USER ENTERED A MASTERCARD CREDIT CARD
if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') {
console.log("The user entered a Mastercard credit card.")
}
ClickToPay.isEnrollmentAvailableForScheme(response.sourceOfFunds.provided.card.scheme, function (canEnroll) {
console.log('Card can be enrolled', canEnroll)
if(canEnroll) {
ClickToPay.checkoutWithNewCard();
}
});
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.cardNumber) {
console.log("Card number invalid or missing.");
}
if (response.errors.expiryYear) {
console.log("Expiry year invalid or missing.");
}
if (response.errors.expiryMonth) {
console.log("Expiry month invalid or missing.");
}
if (response.errors.securityCode) {
console.log("Security code invalid.");
}
} else if ("request_timeout" == response.status) {
console.log("Session update failed with request timeout: " + response.errors.message);
} else if ("system_error" == response.status) {
console.log("Session update failed with system error: " + response.errors.message);
}
} else {
console.log("Session update failed: " + response);
}
}
},
interaction: {
displayControl: {
formatCard: "EMBOSSED",
invalidFieldCharacters: "REJECT"
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
</script>
<script type="text/javascript">
var payloadCallback = function (correlationId, scheme) {
console.log('Payload callback complete with correlation id %s and scheme %s', correlationId, scheme);
};
var errorCallback = function (error) {
console.log('Error callback triggered with error ' + error);
console.log(error);
};
var cancelCallback = function () {
console.log('Cancel callback triggered');
};
function configure() {
ClickToPay.configure({
merchant: {
id: "<your_gateway_merchant_ID>",
name: "<your_gateway_name>",
url: "<your_web_site_URL>"
},
session: {
id: "<your_session_ID>",
wsVersion: <api_version>
},
order: {
amount: <amount>,
currency: "<currency>"
},
interaction: {
//BILLING PREFERENCE WITH ONE OF THE FOLLOWING VALUES: NONE, FULL, POSTAL_COUNTRY
billingPreference: "FULL",
collectShippingAddress: true,
locale: "<locale>",
country: "<country code>"
},
customer: {
email: "<payers_email_address>"//OPTIONAL
},
elements: {
cardList: "cardListContainer",
otp: "otpContainer", // OPTIONAL
dcf: "cardFacilitator"
},
callbacks: {
onComplete: function(correlationId, scheme) {
console.log("onComplete fired");
console.log("Correlation ID: " + correlationId);
console.log("Scheme: " + scheme);
document.getElementById("coid").innerHTML = 'Correlation ID: ' + correlationId + ', Scheme: ' + scheme
},
onStateChange: function(changeInfo) {
console.log("onStateChange fired");
console.log(changeInfo);
},
onError: function(errInfo) {
console.log("onError fired");
console.log(errInfo);
}
}
});
}
function updateEmail() {
ClickToPay.lookupCustomer(document.getElementById("payerEmail").value);
}
</script>
</body>
</html>