- Directives d'intégration
- Fonctionnalités prises en charge (Modes de paiement)
- Mise en œuvre d'une intégration des paiements avec redirection
- Paiements NVP PayPal
PayPal NVP
PayPal est un mode de paiement avec redirection pris en charge sur Mastercard Gateway. Cette page explique les détails de l'intégration spécifique à l'API PayPal NVP, notamment comment configurer votre compte professionnel PayPal de manière à accepter les paiements via la passerelle, les exigences en matière de stratégie de marque, etc. Nous vous recommandons de lire les directives d'intégration pour les paiements avec redirection avant de créer une intégration PayPal.
Conditions préalables
Pour utiliser PayPal comme mode de paiement avec la passerelle, vous devez posséder un compte d'entreprise PayPal configuré pour la passerelle. Pour plus d'informations, voir Configuration de votre compte professionnel PayPal.
Pour vous inscrire à un compte professionnel PayPal, cliquez ici.
Intégration PayPal
Si vous disposez d'une intégration Hosted Checkout PayPal est automatiquement disponible une fois que votre your payment service provider a configuré avec succès le lien d'acquéreur pour PayPal.
Pour plus d'informations, voir Intégration des paiements avec redirection via Hosted Checkout.
Choisissez Direct Payment si vous voulez proposer le mode de paiement PayPal sur votre propre page de paiement.
Expérience de paiement PayPal
Vous pouvez choisir un flux de paiement correspondant le mieux au site de votre magasin.
PayPal permet à vos payeurs de régler leurs achats rapidement et en toute sécurité sur le site de votre magasin ; il leur permet d'utiliser leur compte PayPal pour le paiement et d'indiquer éventuellement des informations d'expédition au site du magasin. Avec PayPal, les payeurs commencent et terminent le processus de paiement sur le site de votre magasin. Les payeurs doivent simplement se connecter à leur compte PayPal et confirmer leur adresse d'expédition et leur mode de paiement. Le site du magasin peut ensuite récupérer les informations d'expédition.
La passerelle prend en charge deux types de flux de paiement PayPal — Raccourci et Marque.
Le flux Raccourci vous permet de rediriger le payeur depuis le site de votre magasin vers le site Web PayPal à l'aide d'un bouton « Payer avec PayPal » placé sur la page de vérification de la carte du site du magasin. Le payeur contourne le flux de paiement normal et paie en utilisant les informations stockées sur son compte PayPal. PayPal indique le nom, l'adresse électronique et l'adresse d'expédition du compte du payeur au site du magasin, permettant un paiement plus rapide en évitant la saisie de ces informations sur le site du magasin.
Le flux Marque permet au payeur de suivre le flux de paiement normal en saisissant ses informations de facturation et d'expédition dans le site du magasin. Lorsque le payeur est invité à choisir son mode de paiement, il sélectionne l'option PayPal placée sur la page de facturation du site du magasin, parallèlement aux autres options de paiement. Contrairement à ce qui se passe dans une transaction par raccourci, c'est le site du magasin qui indique à PayPal l'adresse d'expédition du payeur.
Avec les flux de paiement Raccourci et Marque, vous pouvez choisir d'afficher un bouton « Payer maintenant » ou « Continuer » sur le site Web PayPal.
Le bouton « Payer maintenant » permet au payeur de confirmer le paiement sur le site Web PayPal avant d'être redirigé vers le site de votre magasin. Cette option vous permet d'offrir au payeur une expérience de paiement plus rapide, car le payeur effectue le paiement sur le site Web PayPal.
Le bouton « Continuer » permet au payeur d'être redirigé vers le site de votre magasin pour confirmer le paiement après avoir visualisé tous les détails de la commande. Cette option vous permet de modifier la commande si nécessaire avant d'accepter le paiement (par exemple pour ajouter des frais d'expédition et de traitement en fonction de l'adresse retournée par PayPal). Vous pouvez également inclure d'autres étapes de paiement, par exemple pour effectuer une vente incitative sur votre page de confirmation de commande.
Reportez-vous à Confirmation du paiement ci-dessous pour plus d'informations sur la manière de mettre en œuvre cela dans votre intégration PayPal.
Selon le flux de paiement Marque ou Raccourci, vous pouvez choisir de collecter l'adresse d'expédition du payeur sur le site de votre magasin ou le site Web PayPal, respectivement. Par défaut, PayPal collecte l'adresse d'expédition du payeur sur le site Web PayPal, le payeur étant en mesure de l'ajouter ou de la modifier si nécessaire. Vous pouvez choisir de ne pas afficher l'adresse d'expédition et/ou de désactiver les modifications. Voir Afficher/Remplacer l'adresse d'expédition ci-dessous pour plus d'informations sur la manière de mettre en œuvre cela dans votre intégration PayPal.
L'exemple ci-dessous décrit le flux Raccourci dans lequel le payeur utilise l'adresse d'expédition stockée par PayPal. Le payeur vérifie et confirme le paiement sur le site du magasin du commerçant.
Le flux de paiement est le suivant :
- Un payeur navigue sur le site de votre magasin, sélectionne un produit et clique sur Commander avec PayPal sur la page de paiement.
- Lorsque le payeur clique sur le bouton Payer avec PayPal, vous effectuez un appel
Initiate Browser Payment(Lancer un paiement avec redirection) à la passerelle et redirigez le payeur vers l'URL retournée dans la réponse. - La passerelle redirige le payeur vers le site Web PayPal.
- Le payeur se connecte à son compte PayPal via la page de connexion PayPal.
- Le payeur spécifie l'adresse d'expédition. Il peut sélectionner l'adresse d'expédition préalablement enregistrée par PayPal ou en saisir une nouvelle.
- Le payeur sélectionne une source de financement ou poursuit le paiement en cliquant sur le bouton « Continuer » sur le site Web PayPal.
- PayPal redirige le payeur au site de votre magasin en ligne via la passerelle. Vous extrayez les détails de la transaction, y compris l'e-mail et l'adresse d'expédition du compte du payeur en utilisant l'opération
Retrieve Transaction(Extraire la transaction). - Vous présentez au payeur une page de vérification en fonction de ces informations (vous pouvez, par exemple, ajouter des frais d'expédition et de traitement). Lorsque le payeur clique sur le bouton « Payer maintenant » pour traiter le paiement, vous effectuez un appel
Confirm Browser Payment(Confirmer le paiement avec redirection) à la passerelle. - La passerelle envoie une réponse avec les détails de la transaction, qui indique la réussite du paiement ou tout autre résultat, de manière que vous puissiez présenter son état au payeur.
Référence de l'API Initiate Browser Payment (Lancer un paiement avec redirection) [REST][NVP]
Référence de l'API Retrieve Transaction (Extraire la transaction) [REST][NVP]
Référence de l'API Confirm Browser Payment (Confirmer le paiement avec redirection) [REST][NVP]
Intégration Direct Payment
Direct Payment l'intégration vous permet de proposer le mode de paiement PayPal sur votre propre page de paiement.
Les champs suivants de la demande Initiate Browser Payment (Lancer un paiement avec redirection) sont propres à PayPal ou ont une utilisation spécifique dans l'intégration PayPal. Pour d'autres détails, voir Intégration des paiements avec redirection via Direct Payment.
sourceOfFunds.type = PAYPAL-
Avec PayPal, l'autorisation expire dans les 3 jours à compter de la date d'autorisation. Si vous souhaitez tout de même collecter les fonds après l'expiration de l'autorisation, vous pouvez utiliser l'opération Update Authorization (Mettre à jour l'autorisation).
Par défaut, votre compte de commerçant PayPal est configuré exclusivement pour des collectes uniques. Si vous souhaitez modifier la configuration pour prendre en charge les collectes multiples, veuillez contacter PayPal.Référence de l'API Operation Field (Champ d'opération) [REST][NVP]
-
Lorsque vous initiez un paiement PayPal, vous devez spécifier si vous souhaitez que le payeur confirme le paiement sur le site Web PayPal ou sur le site de votre magasin.
Référence de l'API Confirmation Field (Champ de confirmation) [REST][NVP]
Si la confirmation s'effectue chez le prestataire (PayPal), le site Web PayPal affiche un bouton « Payer maintenant », qui permet au payeur de confirmer le paiement sur le site Web PayPal avant d'être redirigé vers le site de votre magasin. Vous devez envoyer une
Retrieve Transactiondemande à la passerelle pour déterminer le succès ou non du paiement.Si la confirmation s'effectue sur le site de votre magasin, le site Web PayPal affiche un bouton « Continuer », qui permet au payeur d'être redirigé vers le site de votre magasin, où il pourra confirmer le paiement. Vous devez envoyer une demande
Retrieve Transaction(Extraire la transaction) à pour savoir si le payeur a poursuivi le paiement ou non. Si le payeur continue le paiement sur le site de votre magasin, vous devez envoyer un appelConfirm Browser Payment(Confirmer le paiement avec redirection) pour confirmer le paiement auprès de PayPal. La réponseConfirm Browser Payment(Confirmer le paiement avec redirection) contiendra des informations sur le résultat du paiement (réussite ou autre).Référence de l'API Confirm Browser Payment (Confirmer le paiement avec redirection) [REST][NVP]
Dans les deux cas, si le paiement réussit, Retrieve Transaction (Extraire la transaction) retourne :
- l'adresse électronique du compte PayPal du payeur ;
- le nom du titulaire du compte figurant sur le compte PayPal du payeur ;
- les détails d'adresse d'expédition.
-
Vous pouvez gérer la manière dont le payeur vous indique une adresse d'expédition à l'aide de deux champs :
browserPayment.paypal.displayShippingAddress— s'il est défini sur true (par défaut), affiche l'adresse d'expédition sur le site Web PayPal.Référence de l'API Display Shipping Address Field (Champ Afficher l'adresse d'expédition) [REST][NVP]
browserPayment.paypal.overrideShippingAddress— s'il est défini sur true (par défaut), permet au payeur de changer l'adresse d'expédition sur le site Web PayPal.Référence de l'API Override Shipping Address Field (Champ Remplacer l'adresse d'expédition) [REST][NVP]
Par défaut, PayPal collecte pour vous l'adresse d'expédition du payeur sur le site Web PayPal. Si vous choisissez de collecter l'adresse d'expédition du payeur sur le site de votre magasin et ne souhaitez pas que PayPal affiche l'adresse d'expédition au payeur, vous devez définir
browserPayment.paypal.displayShippingAddresssur false. Cela s'applique également lorsqu'une adresse d'expédition n'est pas nécessaire pour une commande (produits exclusivement numériques, par exemple).La passerelle retourne toujours l'adresse d'expédition dans la réponse
Retrieve Transaction(Extraire la transaction) si l'adresse a été indiquée dans la demandeInitiate Browser Payment(Lancer un paiement avec redirection) ou sibrowserPayment.paypal.displayShippingAddressest défini avec la valeur true.Voir le tableau ci-dessous pour connaître les différents scénarios susceptibles de s'appliquer à votre intégration. Vous pouvez choisir un scénario différent pour chaque paiement.
Initiate Browser Payment (Lancer un paiement avec redirection) Site Web PayPal Afficher l'adresse d'expédition Remplacer l'adresse d'expédition L'adresse d'expédition est-elle requise ? L'adresse d'expédition est-elle indiquée ? L'adresse d'expédition est-elle valide ? L'adresse d'expédition est-elle affichée au payeur ? Source de l'adresse d'expédition affichée Le payeur peut-il modifier l'adresse d'expédition ? true (valeur par défaut) true (valeur par défaut) facultatif non Sans objet oui PayPal collecte l'adresse d'expédition. oui true (valeur par défaut) true (valeur par défaut) facultatif oui oui oui PayPal affiche l'adresse d'expédition que vous indiquez dans la demande sur le site Web PayPal. oui true (valeur par défaut) true (valeur par défaut) facultatif oui non oui PayPal ignore l'adresse d'expédition que vous indiquez dans la demande, mais collecte cette adresse sur le site Web PayPal. oui true (valeur par défaut) false requis oui oui oui PayPal affiche l'adresse d'expédition que vous indiquez dans la demande sur le site Web PayPal. non true (valeur par défaut) false requis oui non non PayPal rejette la demande. Sans objet false Sans objet Sans objet oui oui non PayPal ignore l'adresse d'expédition que vous indiquez dans la demande. non false Sans objet Sans objet Sans objet Sans objet non PayPal n'a pas d'adresse d'expédition à afficher. Sans objet Pour tous les scénarios, vous devez utiliser l'adresse d'expédition retournée dans la réponse de la transaction, au cas où celle-ci aurait été modifiée par le payeur sur le site Web PayPal. Veuillez noter que PayPal valide les combinaisons de ville, d'État et de code postal pour les adresses d'expédition aux États-Unis. -
Vous pouvez spécifier les détails des postes dans la demande
Initiate Browser Payment(Lancer un paiement avec redirection) pour indiquer aux payeurs tous les détails de la commande avant qu'ils ne confirment le paiement. Les études sur les consommateurs montrent qu'un plus grand nombre de payeurs valident leurs achats lorsqu'ils voient les articles individuels et les autres détails d'une commande lors du paiement PayPal. Nous vous recommandons donc d'indiquer les informations de commande lorsque vous initiez un paiement PayPal pour encourager les payeurs à poursuivre le paiement plutôt que de l'abandonner.Les postes sont considérés comme indiqués lorsque le nom de l'article ou le prix unitaire est spécifié.
Pour plus d'informations sur les détails des postes, voir Données de poste.
Comment interpréter le résultat de la transaction
Le tableau ci-dessous illustre les codes de réponse de transaction pour les scénarios possibles auxquels vous pouvez devoir faire face après avoir lancé un paiement avec redirection.
Réponse Initiate Browser Payment (Lancer un paiement avec redirection) |
Qu'est-ce que cela signifie ? |
|---|---|
response.gatewayCode=SUBMITTEDresult=SUCCESS |
Redirigez le payeur en utilisant l'URL indiquée dans la réponse. |
response.gatewayCode=SUBMITTEDresult=FAILURE or PENDING or UNKNOWN |
Soumettez une autre demande INITIATE_BROWSER_PAYMENT. |
Réponse Retrieve Transaction/Retrieve Order (Extraire une transaction/Extraire une commande) |
Qu'est-ce que cela signifie ? |
response.gatewayCode=APPROVEDresult=SUCCESS |
Le paiement a réussi. |
response.gatewayCode=PENDINGresult=PENDING |
Le paiement est en attente de vérification dans le système PayPal. Le statut du paiement est mis à jour par la passerelle dès que le système PayPal a informé la passerelle du résultat de la vérification. Voir Paiements en attente. |
response.gatewayCode=CANCELLEDresult=FAILURE |
Le payeur a annulé l'interaction pour ce paiement. Proposez au payeur d'essayer un autre mode de paiement. |
response.gatewayCode=DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTEDresult=FAILURE |
Le paiement a été refusé par PayPal. |
response.gatewayCode=ACQUIRER_SYSTEM_ERRORresult=FAILURE |
L'acquéreur n'a pas pu traiter la transaction. Vous pouvez vouloir demander à l'acquéreur la raison de l'échec du paiement, ou vous pouvez réessayer la transaction RETRIEVE_TRANSACTION. Ou vous pouvez proposer au payeur d'essayer un autre mode de paiement. |
response.gatewayCode=SYSTEM_ERRORresult=FAILURE |
La passerelle n'a pas pu traiter la transaction. |
response.gatewayCode=TIMED_OUTresult=FAILURE |
L'interaction entre le payeur et le système PayPal ne s'est pas terminée avec succès ; cela peut être dû, par exemple, au fait que la passerelle n'a pas reçu de redirection du navigateur du payeur de la part du commerçant dans les 24 heures ou que la passerelle n'a pas pu extraire les détails entre le payeur et le système PayPal et le paiement n'est donc pas terminé. |
response.gatewayCode=UNKNOWNresult=UNKNOWN |
La passerelle n'a pas réussi à savoir si le paiement a réussi ou échoué. |
Paiements en attente
Dans certains cas, la passerelle pourrait retourner un état PENDING (En attente) dans la réponse de transaction. Ce peut être le cas, par exemple, si la transaction fait l'objet d'une évaluation du risque par PayPal. Si le statut est En attente et que vous avez configuré vos propres filtres de gestion de la fraude, vous devriez vous connecter à votre compte professionnel PayPal et vérifier le paiement.
PayPal avertira la passerelle lorsque l'état d'une transaction en attente est mis à jour par PayPal. Vous pouvez extraire le résultat de la transaction mise à jour en utilisant l'opération Retrieve Transaction (Extraire la transaction).
La passerelle considère une transaction PENDING (En attente) comme réussie jusqu'à ce qu'elle reçoive une notification au sujet du résultat de la transaction. Les totaux de commande (montants totaux autorisés/collectés/remboursés) sont mis à jour en tenant compte des transactions en attente. Si la transaction est refusée, les mises à jour sont annulées.
Remboursement des paiements PayPal
Vous pouvez rembourser les paiements traités via PayPal partiellement, en totalité ou en excès ; cependant, notez que le montant de remboursement ne s'applique qu'à la transaction Capture (Collecter) spécifique par rapport à laquelle vous souhaitez rembourser, et non au montant total autorisé. Par exemple, si une autorisation de 100 EUR est suivie de deux collectes partielles de 30 EUR (Capture 1) et de 70 EUR (Capture 2), tout montant remboursé sur cette commande, qu'il soit partiel, total ou en excès, s'applique individuellement à la Capture 1 ou à la Capture 2 et non au montant total de la commande de 100 EUR. En d'autres termes, des remboursements de 50 EUR sur la Capture 1 et la Capture 2 seront considérés respectivement comme excessif et partiel.
- DirectAPI et le montant du remboursement (y compris la tentative de remboursement) ne doit pas dépasser le montant collecté de plus du montant maximal de dépassement autorisé.
- PayPal, dans le cas contraire, l'acquéreur PayPal rejette la demande.
Exigences de la marque pour le site de votre magasin
Cette rubrique vous aide à configurer vos pages de paiement afin de satisfaire aux exigences de PayPal en matière de stratégie de marque.
Lorsque vous proposez PayPal comme mode de paiement à vos payeurs, il est important de vous assurer que l'expérience de paiement du payeur satisfait ou dépasse les normes de mise en œuvre du paiement recommandées par PayPal.
Pour offrir une expérience plus homogène à vos payeurs, la passerelle recommande de personnaliser vos pages de paiement PayPal. Pour ce faire :
- Connectez-vous à votre compte PayPal (à https://www.paypal.com).
- Déterminez si vous utilisez PayPal Merchant Manager. Pour ce faire, regardez l'URL dans la barre d'adresse de votre navigateur. Si l'URL commence par https://paypalmanager.paypal.com/, vous utilisez PayPal Merchant Manager.
- Si vous utilisez PayPal Merchant Manager :
- Cliquez sur Profil.
- Sous Paramètres de paiement hébergé, cliquez sur Styles de page personnalisés.
- Si vous n'utilisez pas PayPal Merchant Manager :
- Sous Profil, cliquez sur Mes outils de vente.
- Sous Vente en ligne, cliquez sur le lien Mettre à jour à droite de Pages de paiement personnalisées.
- Si vous utilisez PayPal Merchant Manager :
Pour obtenir des instructions sur la présentation des éléments de l'interface utilisateur dans vos pages de paiement, voir le Guide des normes de l'interface utilisateur d'Express Checkout sur le site Web de PayPal.
Configuration de votre compte professionnel PayPal
Cette rubrique explique comment configurer votre compte professionnel PayPal pour qu'il fonctionne avec votre intégration à la passerelle.
Pour traiter les transactions avec PayPal, vous devez accorder des autorisations à la passerelle pour les appels d'API précis que la passerelle doit faire en votre nom.
Pour ce faire :
- Connectez-vous à votre compte professionnel PayPal (à l'adresse https://www.paypal.com).
- Déterminez si vous utilisez PayPal Merchant Manager. Pour ce faire, regardez l'URL dans la barre d'adresse de votre navigateur. Si l'URL commence par https://paypalmanager.paypal.com/ vous utilisez PayPal Merchant Manager.
- Si vous utilisez PayPal Merchant Manager :
- Cliquez sur Profil.
- Sous Informations sur le compte, cliquez sur Demander les informations d'identification de l'API.
- Cliquez sur Configurer les informations d'identification et les autorisations de l'API PayPal.
- Si vous n'utilisez pas PayPal Merchant Manager :
- Sous Profil, cliquez sur Mes outils de vente.
- Sous Vente en ligne, cliquez sur le lien Mettre à jour à droite de Accès API.
- Dans la case Option 1, il y aura un lien indiquant Accorder l'autorisation API ou Ajouter ou modifier des autorisations API.
- Si le lien indique Accorder l'autorisation API, cliquez dessus.
- Si le lien indique Ajouter ou modifier des autorisations API, cliquez dessus, puis cliquez sur Ajouter un nouveau tiers.
- Dans la zone Nom d'utilisateur de l'autorisation tierce, entrez le nom d'utilisateur de l'API indiqué par Mastercard et cliquez sur Rechercher. Le nom d'utilisateur de l'API sera indiqué dans l'e-mail de configuration du commerçant envoyé par Mastercard.
- Dans la rubrique Autorisations disponibles, cochez les cases suivantes :
- Utilisez Express Checkout pour traiter les paiements.
- Émettez un remboursement pour une transaction spécifique.
- Autoriser et collecter vos transactions PayPal.
- Cliquez sur Ajouter.
Vous devez indiquer à votre your payment service provider l'adresse électronique de votre compte professionnel PayPal.
Votre your payment service provider se servira de ces détails pour compléter la configuration. Une fois que votre intégration à la passerelle pour PayPal est terminée, vous pouvez Lancer un paiement avec redirection dont le type de paiement sera PAYPAL. Selon votre intégration, vous devrez éventuellement indiquer des champs propres à PayPal, qui sont répertoriés dans la rubrique suivante.
Test de votre intégration
La passerelle propose un émulateur PayPal qui vous permet de tester votre intégration afin d'utiliser la fonctionnalité PayPal via la passerelle.