PayPal Express Boostez votre taux de conversion en offrant le paiement en 2 clics Guide de démarraGe Version 1.1 - Janvier 2009 Leader mondial des paiements en ligne PayPal Express | Guide de démarraGe SO mm aire IntroductIon ............................................................................. p. 3 Étape 1. Ouverture et configuration de votre compte Business ............................................... p. 4 Étape 2. Ouverture d’un compte test .......................................... p. 4 Étape 3. intégration de la solution .............................................. p. 4 Étape 4. Test de l’intégration ..................................................... p. 16 Étape 5. Vérification de l’intégration visuelle ........................... p. 16 www.paypal.fr/developpeurs 2 PayPal Express | Guide de démarraGe iNTrOduCTiON Vous désirez intégrer PayPal express pour ajouter l’option de commande rapide à votre site. Ce document a pour objectif de vous guider dans l’intégration de PayPal express. AttentIon, ce guide d’intégration concerne la version de notre produit qui est basée sur des aPi (Webservice). assurez-vous que vous maîtrisez ce type d’intégration avant de commencer. merci de veiller à utiliser le guide d’intégration officiel des aPi en plus de ce document. Vous voulez recevoir des paiements par carte • Vous avez un site internet • Vous n’avez pas de site internet Vous recevez déjà des paiements par carte • Vous ajoutez PayPal pour augmenter vos ventes • Vous ajoutez PayPal pour booster votre taux de conversion PayPal Intégral PayPal email PayPal option + PayPal Express • Plateforme de paiement sécurisée complète permettant de gérer les paiements par carte effectués sur votre site • Solution de paiement permettant au marchand d’effectuer des demandes de paiement à ses clients grâce à un simple email • Moyen de paiement supplémentaire à ajouter sur son site marchand, en plus de ceux déjà acceptés • Option de commande rapide qui permet aux détenteurs de compte PayPal de payer en seulement 2 clics Intégration en HtLM ou API Aucune intégration nécessaire Intégration en HtLM ou API Intégration en API www.paypal.fr/developpeurs 3 PayPal Express | Guide de démarraGe ÉTAPE 1. Ouverture et configuration de votre compte Business • Créez un compte PayPal Business sur http://www.paypal.fr/marchands • Vérifiez votre compte Business Pour en savoir plus, consultez le guide d’ouverture de compte (PDF) sur www.paypal.fr/documentation-technique ÉTAPE 2. Ouverture d’un compte test L’environnement de test de PayPal (Sandbox) est un environnement autonome dans lequel vous pouvez créer des prototypes et tester les fonctions et aPi de PayPal. il s’agit d’une copie pratiquement identique du site en production de PayPal. Créer un compte de test permettra de tester votre intégration PayPal avant de l’utiliser sur votre site. Pour en savoir plus sur le fonctionnement de l’Environnement de Test, consultez le guide d’utilisation de l’Environnement de Test (PDF) à l’adresse suivante : www.paypal.fr/documentation-technique Pour accéder à l’Environnement de Test de PayPal, connectez-vous sur : https://developer.paypal.com (vous allez être redirigé vers une page en anglais). ÉTAPE 3. Intégration de PayPal Express Note importaNte PayPal Express nécessite l’intégration de PayPal Intégral ou PayPal Option + en version API (Webservice). Assurez-vous que vous maîtrisez l’intégration d’API avant de commencer. Pour en savoir plus sur l’intégration de ces solutions, consultez les guides de démarrage PayPal Intégral ou PayPal Option + disponibles sur www.paypal.fr/documentation-technique www.paypal.fr/developpeurs 4 PayPal Express | Guide de démarraGe Génération des codes d’authentification API afin de pouvoir utiliser l’aPi expressCheckout de PayPal, vous devez au préalable générer des codes d’authentification aPi. • Connectez-vous à partir de https://developer.paypal.com sur le compte test Business Sandbox en cliquant sur enter Sandbox Test Site. • Dans l’Aperçu de votre compte, cliquez sur l’onglet Préférences www.paypal.fr/developpeurs 5 PayPal Express | Guide de démarraGe • La page suivante s’affiche. Cliquez sur le lien Accès à l’API • Cliquez sur demander des informations d’authentification API. Nous recommandons l’utilisation de « la signature aPi », plus simple à utiliser Note importaNte Pour demander des informations d’authentification API, vous devez faire vérifier votre compte test PayPal Business. Pour plus d’informations, consultez le guide d’ouverture de compte (PDF) sur www.paypal.fr/ documentation-integration www.paypal.fr/developpeurs 6 PayPal Express | Guide de démarraGe • Une fois votre compte vérifié, cliquez sur demander des informations d’authentification API. L’écran ci-dessous s’affiche. Vous devez choisir le mode d’authentification. Nous recommandons l’utilisation du « certificat d’API ». Finalisez l’opération en cliquant sur Valider et envoyer. www.paypal.fr/developpeurs 7 PayPal Express | Guide de démarraGe Les API au sein du flux de paiement Les API au sein du flux de paiement Le flux d’un Paiement express est représenté par le schéma suivant : Paiement express PayPal LÉGende : Flux Web 1 requête SetExpressCheckout Site marchand appel Pai jeton Serveur API de PayPal 2 réponse éponse : jeton Achetez PayPal Email [email protected] 3 redirection HTTP Mot de passe https://www.paypal.com/cgi-bin/webscr?cmd=_ express-checkout&token=EC-30S22678F3934250X (exemple de valeur de jeton) Se connecter PayPal 4 redirection HTTP renvoi urL + jeton de la source Confirmation des détails Confirmation d’approvisionnement Continuer Site marchand Confirmation de la commande Paiement Site marchand 5 requête : jeton GetExpressCheckoutDetails réponse : détails sur le client 6 requête : détails de la transaction définitive DoExpressCheckoutPayment 7 Serveur API de PayPal réponse : résultats de la transaction (réussite / échec) 1 Lorsque votre client choisit d’effectuer un paiement à l’aide de PayPal, vous utilisez l’appel d’aPi SetexpressCheckout. 2 PayPal renvoie un jeton : une valeur utilsée pour le suivi du client tout au long de la procédure de paiement. Merci de votre achat et de l’adresse 3 Vous dirigez votre client vers le site PayPal afin de lui permettre de se connecter, de sélectionner une source d’approvisionnement et de confirmer ses coordonnées et informations de livraison. 4 Lorsque vos clients cliquent sur Continuer, PayPal les redirige vers l’urL de retour que vous avez spécifié grâce à l’appel d’aPi SetexpressCheckout. Le jeton d’identifiaction du client est inclus dans l’urL. 5 appelez l’aPi GetexpressCheckoutdetails pour obtenir les détails de votre client de PayPal. envoyez le jeton d’identification du clientt et PayPal renvoie les détails. 6 Lors de la validation du paiement par votre client, appelez l’aPi doexpressCheckoutPayment. PayPal renvoie alors le résultat de la transaction. 7 Vous communiquez les résultats de la transaction à votre client. La redirection vers le site de PayPal est une phase d’authentification et non une phase de paiement. Si le client ne revient pas sur votre site, il n’y a pas eu de paiement. Le paiement devient effectif uniquement lors de l’étape 6 (doexpressCheckoutPayment) et c’est lors de cette étape que PayPal vérifie la disponibilité du montant. La transaction peut donc être refusée lors de cette étape. Pour intégrer PayPal Option +, deux scénarios sont possibles : avec ou sans page de récapitulatif au retour de PayPal. www.paypal.fr/developpeurs 8 PayPal Express | Guide de démarraGe tunnel de commande Le schéma suivant décrit le tunnel de commande dans ce cas : Placement facultatif Votre site Page produit Votre site Panier Votre site Votre site Votre site Votre site Votre site Connexion ou création de compte Choix méthode de livraison Choix méthode de paiement Récupitulatif et paiement Confirmation Création d’une session de paiement. PayPal renvoie le jeton. Site PayPal Connexion Payer récupération de l’dresse de l’acheteur Site PayPal Confirmation Validation du montant exact et paiement. dans le cas du Paiement express, le client peut initier sa commande à travers PayPal à différents moments : > Soit sur la page produit (emplacement facultatif) > Soit à partir du panier L’acheteur clique sur « PayPal ». en étape 1, vous faites appel au Webservice « Setexpresscheckout ». PayPal renvoie un jeton et vous redirigez l’acheteur vers PayPal. L’acheteur se connecte, valide l’achat et est redirigé vers votre site. au retour sur votre site, en étape 2, vous récupérez l’adresse de livraison, le nom, l’adresse e-mail du client en appelant le Webservice « Getexpresscheckoutdetails ». avec ces informations, vous pouvez ensuite soit reconnaître un client existant, soit créer un compte sur votre site pour l’acheteur, la création étant simplifiée puisque vous avez déjà les coordonnées de l’acheteur. il suffit ensuite de demander des informations complémentaires nécessaires à la création d’un compte (mot de passe du compte, inscription à une newsletter, …). avec l’adresse, vous pouvez maintenant également calculer les frais de port et proposer les différentes options à l’acheteur. Vous pouvez afficher une page de récapitulatif et lorsque l‘acheteur clique sur « Payer », vous faites appel en étape 3 au Webservice « doexpressCheckoutPayment » afin de valider le paiement. néanmoins, le paiement est confirmé uniquement après l’appel à «doexpresscheckoutPayment» ! de même, c’est le montant envoyé lors de l’étape 3 qui sera débité. Le montant envoyé en étape 1 est purement indicatif pour PayPal. Nous recommandons néanmoins de nous envoyer un montant réaliste en étape 1, afin que le client puisse choisir le bon moyen de paiement. Le flux précédent est un exemple. Il est possible d’intégrer PayPal Express de différentes façons en fonction de vos besoins et d’éventuelles contraintes. d’autres possibilités de flux sont présentées en annexe. www.paypal.fr/developpeurs 9 PayPal Express | Guide de démarraGe Le détail des API Ce paragraphe détaille les champs obligatoires et recommandés afin d’effectuer un paiement. dans la suite de ce paragraphe, les appels correspondent à l’utilisation de l’aPi NVP. Les champs sont identiques dans l’aPi SOaP. L’aPi paire nom-valeur PayPal (aPi NVP) vous permet de tirer parti des fonctionnalités de l’aPi PayPal en envoyant simplement une requête HTTP à PayPal et en spécifiant des paramètres de requête à l’intérieur de paires nom-valeur. Les urL PayPal à utiliser en NVP sont : > en production Certificat d’aPi : https://api.paypal.com/nvp Signature aPi : https://api-3t.paypal.com/nvp > Sur notre environnement de test Certificat d’aPi : https://api.sandbox.paypal.com/nvp Signature aPi : https://api.sandbox.paypal.com/nvp Paramètres d’authentification Les aPi PayPal permettent aux développeurs de coder de nombreuses fonctions sur la plateforme PayPal, comme le traitement des cartes bancaires, l’envoi d’argent, le remboursement des paiements et les recherches dans un historique des transactions. Pour utiliser les aPi, vous devez disposer d’informations d’authentification qui vous permettent de vous identifier auprès de PayPal. Ces informations consistent en un identifiant et un mot de passe aPi, ainsi qu’une troisième information qui peut être soit une signature aPi, soit un certificat aPi : > Signature aPi La méthode d’authentification la plus simple consiste à utiliser une signature aPi, une valeur chaîne cryptée insérée dans vos appels d’aPi pour vous identifier. > Certificat d’aPi un certificat aPi est un fichier que vous téléchargez à partir du site de PayPal et qui contient une clé privée et un certificat public qui vous identifient auprès de PayPal. Pour des raisons de sécurité, nous recommandons fortement l’utilisation du certificat. Paramètre Facultatif ou Obligatoire Description / Valeur uSer Obligatoire Le champ « username » de vos paramètres d’authentification. PWd Obligatoire Le champ « userpassword » de vos paramètres d’authentification. VerSiON Obligatoire Version d’aPi : 56.0 SiGNaTure Facultatif Le champ « Signature » de vos paramètres d’authentification. www.paypal.fr/developpeurs 10 PayPal Express | Guide de démarraGe réponses aux appels API Chaque appel à l’aPi renvoie une réponse contenant les champs suivants au minimum : Paramètre aCK TimeSTamP COrreLaTiONid VerSiON BuiLd errOrS Description / Valeur Le champ aCK correspond à l’état de l’appel. Les valeurs possibles sont : Success, Failure, SuccessWithWarning, FailureWithWarning. Horodatage par PayPal identifiant unique de la transaction utilisé par PayPal pour tracer une transaction. Version de l’aPi PayPal représentation interne à PayPal en cas d’erreur, PayPal génère les champs suivants avec une description de l’erreur : L_errOrCOde0 : code erreur L_SHOrTmeSSaGe0 : descriptif de l’erreur L_LONGmeSSaGe0 : descriptif de l’erreur SeteXPreSScHecKout Les paramètres suivants sont obligatoires pour effectuer un appel à « Setexpresscheckout » : Paramètre meTHOd Description / Valeur Obligatoire SeTeXPreSSCHeCKOuT Oui reTurNurL urL vers laquelle le navigateur du client est renvoyé après avoir choisi de payer avec PayPal. PayPal rajoute à cette urL deux champs : &token et &Payerid. Ces deux champs sont nécessaires pour effectuer le paiement avec doexpressCheckoutPayment. Oui CaNCeLurL urL vers laquelle le client est renvoyé s'il n'approuve pas l'utilisation de PayPal pour vous payer. Oui Coût total de la commande pour le client. Oui Code devise à trois caractères. Oui Votre numéro de facture ou de suivi personnel. Par défaut, ce champ doit être unique pour chaque transaction. il est également possible d’effectuer une recherche sur ce champ dans votre compte PayPal. Non description des objets achetés par le client. Non amT CurreNCYCOde iNVNum deSC www.paypal.fr/developpeurs 11 PayPal Express | Guide de démarraGe Cet appel renvoie le champ « toKen ». > Lorsque vous avez reçu une réponse de Setexpresscheckout, ajoutez la valeur de l’élément TOKeN de Setexpresscheckout sous forme de paire nom-valeur à l’urL suivante et redirigez-y le navigateur de votre client : https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=value_from_SetexpressCheckoutresponse > exemples de Setexpresscheckout : https://api-3t.paypal.com/nvp?meTHOd=SetexpressCheckout&VerSiON=56.0&PWd=PWdPayPal&uSer=userPayPa l&SiGNaTure=SignaturePayPal&amt=25&CurreNCYCOde=eur&PaYmeNTaCTiON=Sale&returnurl=urLderetou rOK&CaNCeLurL=urLderetourannulation METHOD=SetExpressCheckout &VERSION=56.0 &PWD=PWDPayPal &USER=UserPayPal &SIGNATURE=SignaturePayPal &Amt=25 &CURRENCYCODE=EUR &PAYMENTACTION=Sale &ReturnUrl=URLderetourOK &CANCELURL=URLdeRetourAnnulation doeXPreSScHecKout au retour de PayPal, vous pouvez récupérer les informations sur le client en faisant appel à « Getexpresscheckoutdetails ». Lors de l’appel de votre page, PayPal ajoute deux champs à l’urL de retour : token et Payerid. Le champ Token permet d’effectuer l’appel à « Getexpresscheckoutdetails ». Les paramètres suivants sont obligatoires pour effectuer un appel à « Getexpresscheckoutdetails». > exemples de Getexpresscheckout : https://api-3t.paypal.com/nvp?meTHOd= GetexpressCheckoutdetails&VerSiON=56.0&PWd=PWdPayPal&uSer=us erPayPal&SIGNATURE=SignaturePayPal&TOKEN=TokenReçuParPayPal METHOD=GetExpressCheckoutDétails &VERSION=56.0 &PWD=PWDPayPal &USER=UserPayPal &SIGNATURE=SignaturePayPal &TOKEN=TokenReçuParPayPal Paramètre meTHOd TOKeN Description / Valeur Obligatoire GetexpressCheckoutdetails Oui Valeur du jeton Oui www.paypal.fr/developpeurs 12 PayPal Express | Guide de démarraGe Cet appel renvoie : Paramètre Description / Valeur TOKeN Valeur du jeton emaiL e-mail de l’acheteur PaYer id Numéro unique d’identification du compte PaYerSTaTuS Statut du compte acheteur SaLuTaTiON Formule d’appel du payeur FirSTName Prénom du payeur middLeName LaSTName COuNTrYCOde deuxième prénom du payeur Nom du payeur Pays de résidence du payeur sous forme de code pays iSO 3166 à deux caractères. SHiPTOName Nom de la personne associée à cette adresse SHiPTOSTreeT Première ligne d’adresse SHiPTOSTreeT2 deuxième ligne d’adresse SHiPTOCiTY SHiPTOSTaTe SHiPTOZiP Ville etat ou Province Code postal CuSTOm Champ libre. PayPal renvoie la valeur positionnée dans « Setexpresscheckout » iNVNum Votre numéro de commande. PayPal renvoie la valeur positionnée dans « Setexpresscheckout » PHONeNum Numéro de téléphone. PayPal renvoie ce type de numéro uniquement si les paramètres de vos Préférences de compte marchand nécessitent que l'acheteur en saisisse un. www.paypal.fr/developpeurs 13 PayPal Express | Guide de démarraGe doeXPreSScHecKout au retour de PayPal, vous devez valider le paiement en faisant appel à « doexpresscheckoutPayment ». Lors de l’appel de votre page, PayPal ajoute deux champs à l’urL de retour : token et Payerid. Les paramètres suivants sont obligatoires pour effectuer un appel à « doexpresscheckoutPayment ». Paramètre meTHOd TOKeN Description / Valeur Obligatoire doexpressCheckout Payment Oui Valeur du jeton Oui mode d’obtention du paiement : • Authorization indique que ce paiement est une autorisation de base qui sera traitée par autorisation et collecte. PaYmeNTaCTiON • Order indique que ce paiement est une autorisation de commande qui sera traitée par la fonction autorisation et collecte de PayPal. Oui • Sale indique qu’il s’agit d’une vente finale pour laquelle vous demandez un paiement. PaYerid amT CurreNCYCOde iNVNum deSC Numéro de compte client PayPal Oui Coût total de la commande pour le client Oui Code devise à trois caractères Oui Votre numéro de facture ou de suivi personnel. Par défaut, ce champ doit être unique pour chaque transaction. il est également possible d’effectuer une recherche sur ce champ dans votre compte PayPal. Non description des objets achetés par le client Non www.paypal.fr/developpeurs 14 PayPal Express | Guide de démarraGe Cet appel renvoie : Paramètre TraNSaCTiONid PaYmeNTTYPe Description / Valeur Numéro unique de transaction de paiement indique si le paiement est immédiat ou différé. Nombre limite de caractères : sept caractères d'un octet. Valeurs possibles : none eCheck instant état du paiement : PaYmeNTSTaTuS • Completed : le paiement est terminé et les fonds ont été crédités au solde de votre compte. • Pending : le paiement est en attente. Pour en savoir plus, reportez-vous à l’élément Pendingreason. motif pour lequel le paiement est en attente : • none : pas de motif de mise en attente. • address : le paiement est en attente parce que l'utilisateur n'a pas indiqué d'adresse de livraison confirmée et que vos préférences de réception de paiements sont configurées pour que vous puissiez accepter ou refuser manuellement chacun de ces paiements. Pour modifier votre préférence, accédez à la section Préférences de notification instantanée de paiement dans les Préférences de votre compte. • eCheck : le paiement est en attente parce qu'il a été effectué par le biais d'un chèque électronique qui n'a pas encore été compensé. PeNdiNGreaSON • intl : le paiement est en attente parce que vous détenez un compte hors des etats-unis et que vous ne disposez pas de système de virement. Vous devez accepter ou refuser manuellement ce paiement à partir de votre Aperçu du compte. • multi-currency : vous ne disposez pas de solde dans la devise qui vous a été envoyée et vos Préférences de réception de paiements ne sont pas configurées pour convertir automatiquement ce paiement et l'accepter. Vous devez accepter ou refuser manuellement ce paiement. • verify : le paiement est en attente parce que vous n'avez pas encore le statut Vérifié. Vous devez vérifier votre compte avant de pouvoir accepter ce paiement. • other : le paiement est en attente pour une autre raison que celles indiquées ci-dessus. Pour en savoir plus, contactez le Service clientèle de PayPal. > exemple de doexpresscheckout : https://api-3t.paypal.com/nvp?meTHOd=doexpressCheckoutPayment&VerSiON=56.0&PWd=PWdPayPal&uSer= UserPayPal&SIGNATURE=SignaturePayPal&TOKEN=TokenReçuParPayPal&PAYERID=PayerIDReçuParPayal&PAYM eNTaCTiON=Sale&amT=25&CurreNCYCOde=eur METHOD=DoExpressCheckoutPayment &VERSION=56.0 &PWD=PWDPayPal &USER=UserPayPal &SIGNATURE=SignaturePayPal &TOKEN=TokenReçuParPayPal &PAYERID=PayerIDReçuParPayal &PAYMENTACTION=Sale &AMT=25 &CURRENCYCODE=EUR www.paypal.fr/developpeurs 15 PayPal Express | Guide de démarraGe Autres documentations et liens utiles Guide d’intégration de Paiement express (PdF) https://www.paypalobjects.com/fr_Fr/Fr/pdf/PP_expressCheckout_integrationGuide.pdf Guide d’intégration de la gestion des commandes (PdF) https://www.paypal.com/fr_Fr/pdf/PP_Ordermanagement_integrationGuide.pdf Guide de développement et référence de l’API nVP PayPal (PdF) https://www.paypal.com/fr_Fr/pdf/PP_NVPaPi_developerGuide.pdf Guide de référence de l'API SoAP (PdF) https://www.paypal.com/fr_Fr/pdf/PP_aPireference.pdf Retrouvez toutes ces informations sur l’espace développeurs à l’adresse suivante : www.paypal.fr/developpeurs ÉTAPE 4. Test de l’intégration Pour tester votre intégration grâce à l’environnement de test : • Ouvrez un compte Sandbox (si vous ne l’avez pas déjà fait) • Connectez-vous à votre compte sur https://developer.paypal.com • Créez des comptes test Vendeur (Business) et Acheteur (Personnel) • Vérifiez votre compte test Vendeur • Testez votre intégration Pour plus d’informations sur le fonctionnement de l’Environnement de Test, consultez le guide d’utilisation de l’Environnement de Test (PDF) à l’adresse suivante : www.paypal.fr/documentation-technique Pour accéder à l’Environnement de Test de PayPal, connectez-vous sur https://developer.paypal.com (vous allez être redirigé vers une page en anglais). ÉTAPE 5.Vérification de l’intégration visuelle afin d’optimiser l’expérience d’achat et d’augmenter les ventes, choisissez la meilleure intégration visuelle. Pour cela, consultez le guide d’intégration visuelle (PdF) sur : www.paypal.fr/documentation-technique www.paypal.fr/developpeurs 16 PayPal (Europe) S.à r.l. & Cie, S.C.A. Siège social : 22-24 Boulevard Royal L-2449, Luxembourg RCS Luxembourg B 118 349 Contact PayPal Tél. : 0 800 942 850 (appel gratuit) Email : [email protected] Web : www.paypal.fr/developpeurs Copyright © 1999-2008 PayPal. Tous droits réservés. ">
Public link updated
The public link to your chat has been updated.
