Ce document a pour objectif de donner une première vision claire et rapide de l’intégration
des produits API PayPal tant au niveau technique qu’au niveau visuel.
PayPal dispose de documentations supplémentaires que vous pourrez vous fournir en
fonction des spécificités du projet.
Par ailleurs, PayPal France a mis en place un processus de certification qui repose
notamment sur les principes d’intégration exposés dans ce document ; le but de cette
certification est de récompenser les partenaires qui ont fait les efforts d’intégration
technique et visuelle qui permettent d’offrir au marchand et à l’acheteur final une meilleure
expérience de nos solutions.
Au-delà de la bonne intégration de nos principales solutions, les points suivants seront
particulièrement importants dans le processus de certification:
• Le respect des bonnes pratiques d’intégration Visuelle (1.2):
oExpérience souhaitée pour le marchand : le marchand peut différentier
les 3 offres PayPal (sur le site du partenaire et/ou au sein de l'interface
de gestion de sa boutique en ligne) et choisir celle qui lui convient ; il
peut facilement afficher le logo qui correspond à l'offre qu'il a choisie
dans les différentes sections de sa boutique.
oExpérience souhaitée pour l'acheteur : le marchand présente à
l'acheteur tous les moyens de paiement disponibles, c'est-à-dire les
cartes bancaires et privatives, le compte bancaire et le compte PayPal
dans le cas de PayPal Intégral, ou le compte PayPal uniquement dans le
cas de PayPal Option+ et PayPal Express.
• L’utilisation du traceur Bouton Source (BN Code) (2.1.2.1):
Le BN Code est un Identifiant de transactions réalisées via un partenaire
PayPal. Merci de contacter PayPal pour obtenir le vôtre. (partenaires@paypal.com)
• La gestion des transactions via l’IPN (2.2.2)
Les critères de certification pourront être complétés pour inclure de nouvelles
fonctionnalités de PayPal afin d'offrir aux marchands et aux acheteurs finaux les versions de
nos solutions les plus performantes.
Si vous souhaitez obtenir la certification, merci de nous contacter en envoyant un email à
L’intégration de PayPal permet de proposer à vos clients une expérience basée sur la
simplicité et la sécurité. L’utilisation des API PayPal permet d’intégrer PayPal de deux
façons :
• Simplifier et raccourcir le tunnel de commande pour le client grâce à une utilisation
optimisée de PayPal à partir du panier de commande (PayPal Express).
• Lister PayPal comme un moyen de paiement additionnel à côté des autres moyens de
paiements (PayPal Option+)
• Proposer également un paiement par cartes bancaires et/ou cartes privatives via la
plateforme PayPal (PayPal Intégral)
1.1 Scénario de commande
1.1.1 FLUX PAYPAL EXPRESS (ECS)
L’intégration de PayPal Express permet à l’acheteur de passer une commande rapidement
sans avoir à remplir de formulaire sur le site marchand
3. Le client clique sur « Continuer ». Il est redirigé vers la page de confirmation
d’achat, sur le site du marchand. L’adresse de livraison est déjà remplie à
l’aide des informations fournies par PayPal. Le champs « Mode de
paiement » indique également PayPal comme mode de paiement et
affichera l'adresse email du compte PayPal du client.
•
PayPal transmet des
informations liées à
l’acheteur au site
marchand
•
Le site marchand prérenseigne les
informations
nécessaires à la
finalisation de la
• Nom, prénom de l’acheteur,
• Adresse de livraison
• Adresse email
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, …)
À cette étape, aucune transaction n’est commencée. Le client a seulement
donné son accord au site marchand pour débiter son compte PayPal.
4. Lorsque le client clique sur le bouton de confirmation d’achat du site
marchand, la transaction réelle sera initiée et le client sera dirigé vers la
page de remerciement.
PayPal apparaîtra sous la forme d'un moyen de paiement supplémentaire sur la page
du panier d'achat du site marchand à côté d'autres modes de paiement :
1. Le client sélectionne PayPal comme moyen de paiement
2. Le client est redirigé vers une page de connexion à PayPal
3. Une fois connecté, la page de vérification PayPal s’affiche. Sur cette page, il peut
utiliser la source d'approvisionnement par défaut ou en sélectionner une autre. Le
champ « Adresse de livraison» de la page affiche l'adresse de livraison fournie sur le
site du marchand et le client ne pourra pas la modifier. Cette page sera configurée
pour que le bouton « Continuer » soit remplacé par « Payer » afin d'indiquer que la
transaction va avoir lieu dès que le client cliquera dessus.
4. Le client clique sur ce bouton « Payer » : il est redirigé vers la page de
remerciement. Aucune transaction n’est réellement effectuée jusqu'à ce que le client
revienne sur le site du marchand et que soit envoyée la requête API finale.
Le flux PAYPAL INTEGRAL est en grande partie identique à celui de PayPal OPTION+. Seule
change la page d’identification sur le site PayPal qui propose alors la possibilité de payer
avec un autre moyen paiement que PAYPAL, sans que l’acheteur ait à se créer un compte
PAYPAL :
Note1 : Il est recommandé de pré-remplir les noms et contacts de l’acheteur identifié,
afin d’accélérer le processus de paiement.
Note2 : Merci de vous rendre sur le site www.PayPal.fr pour obtenir une liste à jour de tous
les autres moyens de paiement proposés par PayPal dans chaque pays.
PayPal permet de procéder à un premier paiement direct au crédit d’une adresse email non
rattachée à un compte business PayPal.
Il est ainsi possible d’activer le moyen de paiement PayPal pour n’importe quel marchand,
sans que celui-ci n’ait à créer un compte PayPal au préalable.
Il suffit juste de procéder un paiement en mode direct (mode sale) vers l’adresse email
connue du marchand.
Ce premier paiement restera « en attente » (statut pending) avec pour raison « unilateral »
tant que l’adresse email du marchand ne sera pas rattachée à un compte « business »
PayPal. Ce paiement « en attente » sera également automatiquement notifié au marchand
dans un email expliquant les démarches à suivre pour ouvrir un compte PayPal et récupérer
les fonds en suspend.
Suite à l’ouverture du compte, le marchand devra configurer une «
1.2.1 COMMENT PRESENTER PAYPAL AUX VISITEURS DE VOTRE
SITE ?
Une intégration visuelle optimale de PayPal et de vos moyens de paiement permet
d’informer vos clients, et contribue à augmenter votre taux de conversion. Grâce à nos
recommandations sur l’intégration visuelle de PayPal, vous pouvez augmenter jusqu’à 15%
vos ventes1.
Vous trouverez dans le document en ligne ci-après les éléments de recommandations pour
optimiser votre tunnel de commande et assurer à vos clients une expérience d’achat
rassurante.
https://www.paypal-
france.fr/webscr/fr_FR/pdf/PayPal_G
uide_Integration_Visuelle.pdf
1
Source : Etude interne réalisé auprès d’un panel de marchands utilisant PayPal sur le marché allemand. Octobre 2008: 15% ventes
additionnelles selon August Beyer, PDG de Zoo York. 12% ventes additionnelles selon Martina Eltlin, PDG de Textoys.de. 10%
ventes additionnelles selon Richard Colman, PDG de Maxtrader. Etude réalisée de Janvier à Octobre 2008.
Dans le cas d’une intégration de PayPal dans une solution standardisée, il est important que
le marchand puisse choisir de présenter à l'acheteur toutes les solutions de paiement
disponibles, c'est-à-dire les cartes bancaires et privatives, le compte bancaire ou le compte
PayPal dans le cas de PayPal Intégral, ou le compte PayPal dans le cas de PayPal Option+ et
PayPal Express.
Une intégration claire du choix des différentes solutions dans le back office et une
présentation cohérente des logos en back office est donc importante.
Un Paiement via PayPal implique l’utilisation de 2 Appels APIs :
- SetExpressCheckout, qui initie la transaction
- et DoExpressCheckout, qui confirme le paiement via PayPal depuis le site marchand
- l’appel GetExpressCheckOut, est lui complémentaire, et permet au marchand d’obtenir
des données liées à la transaction en cours et à l’acheteur (nécessaire pour le paiement
Express).
2.1.1 SCHEMA DES WORKFLOW DE PAIEMENT
Les schémas suivants présentent les modèle de scenarii possibles sur les deux modes
d’intégration des APIs PayPal
Envoyé immédiatement avant la redirection du client vers PayPal, l'appel
SetExpressCheckout initie la demande de transaction et contient toutes les informations sur
l'aspect et le fonctionnement des pages PayPal.
2.1.2.1 Variables à retourner quelque soit le type d’intégration
Intégration NVP
RETURN URL RETURN URL
CANCEL URL CANCELURL
AMOUNT ORDERTOTAL
Intégration SOAP
Description
adresse vers laquelle le client est redirigé après avoir
accepté la transaction. Dépend du flux.
adresse vers laquelle le client est redirigé s'il annule
l'achat sur les pages PayPal. Généralement, il s'agit
de la page de votre site d'où il est venu.
montant estimé de la transaction. Ce champ, qui doit
être la meilleure estimation au moment de la
requête, n'est pas utilisé pour la transaction réelle.
- Lorsqu'un jeton de session (TOKEN) a été renvoyé par PayPal, vous devez
rediriger le client vers le site PayPal, où il sera authentifié et acceptera la
transaction.
- La base de cette URL est “https://www.PayPal.com/cgi-bin/webscr?”.
- Un paramètre “cmd” de valeur “_express-checkout” et un paramètre “token”
ayant pour valeur le jeton de session sont nécessaires.
- Un paramètre facultatif “useraction” de valeur “commit” transformera les
boutons Continuer de la page de vérification PayPal en boutons Payer.
- Lorsque le client en aura validé ses informations sur le site PayPal, il sera
redirigé vers le vôtre selon la valeur de ReturnURL ou de CancelURL spécifiée
dans l'appel SetEC, suivie du jeton de session sous forme de paramètre “token”.
- Si ReturnURL est utilisé, un paramètre “PayerID” contenant l'identifiant unique
du compte PayPal du client sera également ajouté.
Exemple d’URL de redirection avec bouton « continuer » :
L'appel GetEC est effectué lorsque le client est redirigé vers le site du marchand selon l'URL
de retour passée dans l'appel SetEC. Sa seule entrée est le jeton retourné par l'appel SetEC.
L'appel GetEC retourne toutes les informations relatives au client : nom, adresse email,
adresse de livraison, pays, identifiant de payeur, état du compte et éventuellement numéro
de téléphone
L'appel DoEC est effectué après que vous ayez reçu la réponse de la requête GetEC. Pour le
flux ECS, il n'est réalisé qu'après le clic du client terminant l'achat sur votre page de
confirmation.
Pour le flux ECM, il est effectué immédiatement après que le client ai cliqué sur le bouton
Payer de la page de vérification PayPal.
L'appel DoEC necessite le jeton (token) de session de l'appel SetEC et l'identifiant de payeur
du client, tous deux pouvant être récupérés de la réponse à l'appel GetEC ou de l'URL
utilisée par PayPal pour rediriger le client vers le site du marchand.
généré par l'appel SET EC, peut être récupéré à partir
de la réponse GET ou de l'URL vers laquelle le client a
été redirigé à partir du site PayPal
identifiant unique du compte PayPal du client, peut être
récupéré à partir de la réponse GET ou de l'URL vers
laquelle le client a été redirigé à partir du site PayPal.
Mode d’obtention du paiement :
- Authorization
- Order
- Sale
valeur unique fournie par le marchand et identifiant la
transaction sur son système. Peut être trouvée par une
recherche sur le système PayPal et s'affiche sur le
rapport PayPal
Code Identifiant de transactions réalisées via un
partenaire PayPal
Merci de contacter PayPal pour obtenir le votre.
(partenaires@paypal.com)
AMOUNT &
CURRENCYCODE
SHIPTOADDRESS SHIPTOADDRESS
NOTIFYURL
AMOUNT
NOTIFYURL
montant réel de la transaction, devant correspondre au
montant que voit réellement l'acheteur sur les pages de
vérification finales du site du marchand.
L’adresse ne doit être envoyée à cet étape que si celle-
ci a changé entre le SetEC/GetEC et le DoEC
Votre URL pour la réception de la Notification
instantanée de paiement (IPN) concernant
cette transaction. L’utilisation de l’IPN est
fortement recommandé afin de gérer les
transactions en Attente.
L'appel DoExpressCheckout retourne un numéro de transaction. Le type de numéro de
transaction dépend de la valeur du champ PaymentAction. En cas de vente immédiate
(valeur de PaymentAction : Sale), le numéro de transaction représente la collecte des fonds.
L'appel DoExpressCheckout retourne un numéro de commande PayPal. C'est le début de la
transaction réelle sur le système PayPal. Ce numéro de commande PayPal peut être utilisé
pour Autorisation et collecte.
Pour aller plus loin : https://cms.PayPal.com/us/cgi-bin/?cmd=_render-
Une transaction PayPal peut revenir avec un état “en attente” (pending), dans le cas où les
fonds sont alimentés par un e-cheque par exemple.
Si le champ paymentstatus a pour valeur « completed », alors le paiement a été accepté.
Si ce champ a pour valeur « pending », alors le champ pendingreason donne la raison du
pending.
Attention : la transaction a potentiellement été accepté, mais il manque une action pour
que les fonds soit disponible.
Les principales raison de pending sont :
Authorizationle paiement a été effectué en mode autorisation et n’a pas
encore été capturé.
Echeckle 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é
multi-currency: vous ne disposez pas de solde dans la devise quivous 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.
Orderle paiement a été effectué en mode order et n’a pas encore
été capturé ou autorisé.
PaymentreviewCette transaction est en cours de révision par l’équipe Risk
de PayPal. L’état final de cette transaction sera connu d’ici
24 heures.
Unilateral Ce paiement est en attente car il a été effectué sur une
adresse email non rattaché à un compte PayPal.
Lorsque le statut de la transaction change, PayPal envoie notification instantanée de
paiement (IPN) avec le nouveau statut.
Le marchand peut refuser tout paiement par e-cheque. Ce refus requiert un paramétrage
dans le compte marchand PaPal
2.2.2 NOTIFICATION INSTANTANEE DE PAIEMENT (IPN)
La notification instantanée de paiement (IPN) est une interface PayPal qui permet de gérer
la confirmation en temps réel des achats et les communications de serveur à serveur.
La IPN émet une notification et une confirmation immédiate des paiements PayPal que vous
recevez et indique l'état et des données supplémentaires concernant les transactions en
attente, annulées ou ayant échoué.
Les remboursements peuvent uniquement être effectués contre des paiements et ce dans
une limite de 60 jours après paiements initiaux.
Plusieurs remboursements peuvent être effectués contre un paiement unique dans la
mesure où le total de leurs montants ne dépasse pas le montant initial du paiement.
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.
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 URLS PayPal à utiliser en NVP
sont :
Adresse e-mail d'un compte PayPal, qui a accordé la
permission de faire cet appel.
Ne Passer ce paramètre que si vous appelez une API pour un
autre nom de l'utilisateur
(voir third party authorisation)
.
2.3.2 THIRD PART AUTORISATION
La « third part authorisation » doit être utilisée si un marchand souhaite procéder à des
appels API Paypal à travers des développements réalisé par un tiers. Spécialement adaptée
aux Shopping Cart proposant des plateformes standardisées de e-commerce à leurs clients,
l’utilisation de la « third party authorisation » nécessite plus particulièrement :
- l’utilisation de l’adresse email du marchand final dans le champs SUBJECT de
l’appel API d’identification aupres de PayPal
- La configuration de son compte PayPal par marchand final pour autoriser le site
tier à procéder des transactions depuis/ vers son compte. (Une procédure
détaillée est fournie en annexe de ce document)
PayPal exige que les marchands consignent des informations spécifiques. Ces éléments sont
retournés dans des réponses API.
•Transaction ID: si la transaction réussit, vous devez conserver son
identifiant pour procéder par la suite au rapprochement. Vous devez
stocker cet identifiant sur votre système s'il est retourné.
•Correlation ID: si vous êtes amené à demander à notre équipe de gestion
des comptes ou MTS l'examen approfondi d'une transaction spécifique,
vous devrez leur fournir l'ID de corrélation. Vous devez stocker cet
identifiant sur votre système s'il est retourné. Le corrélation ID est retourné
en réponse standard à tous les appels API.
La liste suivantes présentent les états de transactions possible, leur évolution possible, ainsi
que les raisons d’un statut « en attente » :
Statuts Statuts suivants possible
Completed: Le paiement a été achevé et les
fonds ont été ajoutés avec succès à votre solde
de compte.
Denied: Vous avez refusé le paiement. Cela
arrive seulement si le paiement était déjà en
attente pour une des raison décrites dans la
section PendingReason.
Expired: La période d'autorisation pour ce
paiement a été atteinte.
•Canceled-Reversal: Cela signifie qu'un
renversement a été annulé. Par exemple, vous
avez gagné un litige contre un client et que les
fonds de la transaction vous ont été rendu.
Failed: Le paiement a échoué. Cela arrive
seulement si le paiement a été opéré depuis
compte bancaire de votre client.
In-Progress: La transaction ne s'est pas
terminée. Par exemple une autorisation peut
être en attente d'une capture
Partially-Refunded
Refunded
Completed
Denied
Failed
Partially-Refunded: Le paiement a été
partiellement remboursé.
Pending: Le paiement est attente. Voir le
champ PendingReason pour plus
d'informations.
Refunded: Vous avez remboursé le paiemen.
Voided: Une autorisation pour cette
transaction a été annulée.
•Reversed: Un paiement a été reversé en raison
d'un chargeback ou d'autre type de
renversement. Les fonds ont été enlevés de
votre solde de compte et rendus à l'acheteur.
La raison du renversement est spécifiée dans le
champ ReasonCod
address: Le paiement est en suspens parce que votre client n'a pas inclus d'adresse
d'expédition confirmée et vos préférences de réception de paiement est paramétrée de
manière à ce que vous puissiez manuellement accepter ou refuser chacun des paiements.
Pour changer votre préférence, allez à la section Préférences de votre Profil..
authorization: Le paiement est en suspens parce qu'il a été autorisé, mais pas finalisé. Vous
devez capturer les fonds d'abord.
echeck: Le paiement est en suspens parce qu'il a été fait par un eCheck qui n'a pas encore
était clarifié.
intl: Le paiement est en suspens parce que vous avez un compte non-américain et n'avez
pas de mécanisme de retrait. Vous devez manuellement accepter ou refuser ce paiement .
multi-currency: Vous n'avez pas de solde en devise envoyée et vous n'avez pas
paramétrévos préférences pour automatiquement convertir les devises et accepter ce
paiement. Vous devez manuellement accepter ou refuser ce paiement.
order: Le paiement est en suspens parce qu'il fait partie d'une une commande qui a été
autorisé, mais pas totalement finalisé.
paymentreview: Le paiement est en suspens pour revue par le service de gestion des
risques de PayPal
verify: Le paiement est en suspens parce que vous n'êtes pas encore vérifiés. Vous devez
vérifier votre compte avant de pouvoir accepter ce paiement.
other
:
Le paiement est en suspens pour une raison d'autre que celles inscrites ci-dessus
Le champ ACK correspond à l’état de l’appel. Les valeurs possibles
Identifiant unique de la transaction utilisé par PayPal pour tracer
En cas d’erreur, PayPal génère les champs suivants avec une
3.2 Codes erreur
Chaque appel à l’API renvoie une réponse contenant les champs suivants au
minimum :
Paramètre
ACK
TIMESTAMP
Description / Valeur
sont : Success, Failure, SuccessWithWarning, FailureWithWarning
Horodatage par PayPal
CORRELATIONID
VERSION
BUILD
ERRORS
une transaction
Version de l’API PayPal
Représentation interne à PayPal
description de l’erreur :
L_ERRORCODE0: code erreur
L_SHORTMESSAGE0 : descriptif de l’erreur
L_LONGMESSAGE0 : descriptif de l’erreur
Les codes erreurs peuvent être groupés en fonction de la façon dont ils peuvent être traités.
Certaines erreurs requièrent des actions du côté du marchands
•Fix: Ce type d’erreur doit être identifiée durant la phase de test du site.. Une
modification du code source du marchand est requise pour corriger cette erreur
•Escalate: Cette erreur indique un problème avec PayPal ou avec le compte
Marchand. Une communication de cette erreur à vos contacts en account
management ou en integration management est requis pour la résolution de ce
problème.
•Message: Certaines erreurs indiquent un problème avec le compte business du
marchand ou avec sa source de fond. Dans certains cas, un nouvel essai donnera un
résultat concluant. Cela dit si ce type d’erreurs à lieu lors d’une commande d’un
client, il sera peut être nécessaire d’afficher un message lui expliquant comment
annuler la transaction.
•Retry: Certains erreurs son dues à des problèmes occasionnels de charges. Si
l’erreur est récurrente, il sera nécessaire de réaliser un message pour les utilisateurs
et/ ou contacter vos support PayPal.
Une liste exhaustive des code erreur PayPal est disponible ici:
3.3 Process de configuration d’une 3rd part Authorisation
Voici une proposition de guide de configuration à soumettre aux marchands finaux pour tout
activation de PayPal sur son site e-commerce :
Configurer votre interface back office PayPal
Pour pouvoir utiliser le moyen de paiement PayPal sur votre site, vous devez, vous aussi, disposer d’un
compte PayPal. Ce compte doit être de type « Business » (choix du type de compte au moment de la création
sur www.paypal.fr).
C’est sur ce compte que seront déposés les fonds collectés chaque soir. Vous pouvez bien sûr choisir
d’effectuer un virement de ces fonds à destination de votre compte bancaire.
Si vous avez plusieurs boutiques de production, nous vous invitons à créer un compte PayPal par boutique.
Sur votre compte PayPal, vous devrez autoriser PARTENAIRE à effectuer des appels vers PayPal en votre nom.
Pour ce faire, il vous suffit de suivre la procédure qui suit.
Connectez-vous à votre compte PayPal et cliquez sur l’onglet Préférences
La page suivante s’affiche. Cliquez sur le lien Accès à l’API
3.4 Flux de création de compte avec PayPal Express
Buyer Opts to
checkout with
PayPal Express
Checkout
PayPal:
SetEC
Redirect
GetECDetails
Merchant stores PayPal
payer ID against their
account information
PayPal:
DoEC Payment
Link between PP and
customer Accounts?
No
Buyer Logged into
customer account
No
Log In Page
Existing customer
account ?
No
Create customer
account with details
returned by PayPal
Yes
Yes
Create Link between
PP and Merchant
accounts
Yes
If PayPal returns all the
required information to
create an account, then no
user interaction is required at
this point. Password for the
account and additional
confirmation can be emailed
to the user.
Confirmation page
Receipt Page
3.5 Migration vers une intégration API
Une intégration des solutions PayPal en mode API est importante pour obtenir une
certification API.
Dans le cas d’une intégration préexistante en mode Standard (HTML), il est recommandé
d’effectuer une migration de manière progressive de tous vos marchands via un flot dit
« unilaterial » décrit en 1.1.4