PayPal Express 2009 Manuel utilisateur

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
xxxxxx@paypal.fr
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 : marchands@paypal.fr
Web : www.paypal.fr/developpeurs
Copyright © 1999-2008 PayPal. Tous droits réservés.
">