PAYPAL Express - 2009, Express - 2012 Guide de démarrage [fr]

Version 1.1 - Janvier 2009

Boostez votre taux de conversion

en offrant le paiement en 2 clics

PayPal Express

Leader mondial des paiements en ligne

GUIDE DE DÉMARRAGE

www.paypal.fr/developpeurs

2

PayPal Express | GUIDE DE DÉMARRAGE

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

SOMMAIRE

www.paypal.fr/developpeurs

3

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 recevez déjà

des paiements par carte

• Vous avez un site

Internet

• Vous n’avez pas
de site Internet

• 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

4

PayPal Express | GUIDE DE DÉMARRAGE

• Créez un compte PayPal Business sur http://www.paypal.fr/marchands

• Vériez votre compte Business

Pour en savoir plus, consultez le guide d’ouverture de compte (PDF) sur www.paypal.fr/documentation-technique

ÉTAPE 1. Ouverture et configuration de votre compte Business

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 2. Ouverture d’un compte test

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

É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.

www.paypal.fr/developpeurs

5

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

6

PayPal Express | GUIDE DE DÉMARRAGE

• La page suivante s’afche. Cliquez sur le lien

Accès à l’API

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

• Cliquez sur

. Nous recommandons l’utilisation de

« la signature API », plus simple à utiliser

www.paypal.fr/developpeurs

7

PayPal Express | GUIDE DE DÉMARRAGE

• Une fois votre compte vérié, cliquez sur

. L’écran
ci-dessous s’affiche. Vous devez choisir le mode d’authentification. Nous recommandons l’utilisation
du «

». Finalisez l’opération en cliquant sur

et envoyer.

www.paypal.fr/developpeurs

8

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 :

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.

Paiement express PayPal

Merci de votre achat

Confirmation de la source
d’approvisionnement
et de l’adresse

Site marchand

Achetez

Site marchand

Paiement

Site marchand

Serveur

API

de PayPal

Serveur

API

de PayPal

7

2

1

Requête

SetExpressCheckout

3

Redirection HTTP

https://www.paypal.com/cgi-bin/webscr?cmd=_

express-checkout&token=EC-30S22678F3934250X

(exemple de valeur de jeton)

4

Redirection HTTP

Renvoi URL + jeton

5

Requête : jeton

GetExpressCheckoutDetails

Réponse : résultats de la transaction

(réussite / échec)

6

Requête : détails de la transaction définitive

DoExpressCheckoutPayment

Réponse : détails sur le client

Se connecter

PayPal

Email

[e-mail]

Mot de passe

Continuer

PayPal

Confirmation des détails

Confirmation

de la commande

LÉGENDE : Flux Web Appel PAI jeton

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.

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 A ppelez 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.

www.paypal.fr/developpeurs

9

PayPal Express | GUIDE DE DÉMARRAGE

Tunnel de commande

Le schéma suivant décrit le tunnel de commande dans ce cas :

Placement facultatif

Création d’une
session de paiement.
PayPal renvoie le jeton.

Récupération
de l’dresse de
l’acheteur

Validation
du montant
exact et
paiement.

Panier

Votre site

Page

produit

Votre site

Connexion
ou création
de compte

Votre site

Choix

méthode

de livraison

Votre site

Choix

méthode

de paiement

Votre site

Connexion

Site PayPal

Confirmation

Site PayPal

Récupitulatif

et paiement

Votre site

Payer

Confirmation

Votre site

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 «

». En étape 1, vous faites appel au Webservice «

».

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 «

».

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.

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 ux 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

10

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.

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

11

PayPal Express | GUIDE DE DÉMARRAGE

Paramètre Description / Valeur

ACK

Le champ ACK correspond à l’état de l’appel. Les valeurs possibles sont :
Success, Failure, SuccessWithWarning, FailureWithWarning.

TIMESTAMP Horodatage par PayPal

CORRELATIONID Identifiant unique de la transaction utilisé par PayPal pour tracer une transaction.

VERSION Version de l’API PayPal

BUILD Représentation interne à PayPal

ERRORS

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

Réponses aux appels API

Chaque appel à l’API renvoie une réponse contenant les champs suivants au minimum :

SETEXPRESSCHECKOUT

Les paramètres suivants sont obligatoires pour effectuer un appel à «

» :

Paramètre Description / Valeur Obligatoire

METHOD 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

AMT Coût total de la commande pour le client. Oui

CURRENCYCODE Code devise à trois caractères. Oui

INVNUM

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

DESC Description des objets achetés par le client. Non

www.paypal.fr/developpeurs

12

PayPal Express | GUIDE DE DÉMARRAGE

Cet appel renvoie le champ «

».

> Lorsque vous avez reçu une réponse de

, ajoutez la valeur de l’élément TOKEN

de

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

>

E

:

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

METHOD=GetExpressCheckoutDétails

DOEXPRESSCHECKOUT

Au retour de PayPal, vous pouvez récupérer les informations sur le client en faisant appel à
«

».
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 à «

».

Les paramètres suivants sont obligatoires pour effectuer un appel à «

».

>

:

https://api-3t.paypal.com/nvp?METHOD= GetExpressCheckoutDetails&VERSION=56.0&PWD=PWDPAyPal&USER=Us

erPayPal&SIGNATURE=SignaturePayPal&TOKEN=TokenReçuParPayPal

Paramètre Description / Valeur Obligatoire

METHOD GetExpressCheckoutDetails Oui

TOKEN Valeur du jeton Oui

www.paypal.fr/developpeurs

13

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 Deuxième prénom du payeur

LASTNAME Nom du payeur

COUNTRYCODE 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 Ville

SHIPTOSTATE Etat ou Province

SHIPTOZIP Code postal

CUSTOM Champ libre. PayPal renvoie la valeur positionnée dans «

»

INVNUM

Votre numéro de commande. PayPal renvoie la valeur positionnée dans
«

»

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

14

PayPal Express | GUIDE DE DÉMARRAGE

DOEXPRESSCHECKOUT

Au retour de PayPal, vous devez valider le paiement en faisant appel à «

».
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 à «

».

Paramètre Description / Valeur Obligatoire

METHOD DoExpressCheckout Payment Oui

TOKEN Valeur du jeton Oui

PAYMENTACTION

Mode d’obtention du paiement :

• Authorization indique que ce paiement est une autorisation

de base qui sera traitée par Autorisation et collecte.

• Order indique que ce paiement est une autorisation

de commande qui sera traitée par la fonction Autorisation
et collecte de PayPal.

• Sale indique qu’il s’agit d’une vente finale pour laquelle

vous demandez un paiement.

Oui

PAYERID Numéro de compte client PayPal Oui

AMT Coût total de la commande pour le client Oui

CURRENCYCODE Code devise à trois caractères Oui

INVNUM

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

DESC Description des objets achetés par le client Non

www.paypal.fr/developpeurs

15

PayPal Express | GUIDE DE DÉMARRAGE

Cet appel renvoie :

Paramètre Description / Valeur

TRANSACTIONID Numéro unique de transaction de paiement

PAYMENTTYPE

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

PAYMENTSTATUS

État du paiement :

• 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.

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é.

• 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.

>

:

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

www.paypal.fr/developpeurs

16

PayPal Express | GUIDE DE DÉMARRAGE

ÉTAPE 4. Test de l’intégration

• 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ériez 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

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

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. : [phone] (appel gratuit)
Email : [e-mail]
Web : www.paypal.fr/developpeurs

Copyright © 1999-2008 PayPal. Tous droits réservés.