PAYPAL Partenaires - 2009 User Manual [fr]

Présentation et

cadrage des solutions partenaires.

Version 1.0 – September 2009

Sommaire

PREAMBULE – CERTIFICATION PAYPAL 3

1.1

Scénario de commande 4

1.1.1 Flux PAYPAL EXPRESS (ECS) 4

1.1.2 Flux PAYPAL OPTION + (ECM) 8

1.1.3 Flux PAYPAL INTEGRAL 9

1.1.4 Embarquement accéléré des marchands 10

1.2

Intégration visuelle de PayPal 11

1.2.1 Comment présenter PayPal aux visiteurs de votre site ? 11

1.2.2 Comment présenter PayPal dans le backoffice marchand ? 12

2. INTEGRATION TECHNIQUE DES SOLUTIONS PAYPAL 13

2.1

Appels API 13

2.1.1 Schéma des workflow de paiement 13

2.1.2 SETEXPRESSCHECKOUT (SetEC) 14

2.1.3 URL de redirection 16

2.1.4 GETEXPRESSCHECKOUT (GetEC) 17

2.1.5 DOEXPRESSCHECKOUT (DoEC) 17

2.2

Traitement de la transaction PayPal 19

2.2.1 Paiements en attente 19

2.2.2 Notification instantanée de paiement (IPN) 20

2.2.3 Remboursements 20

2.3

Détails d’intégration 21

2.3.1 Informations d'authentification API 21

2.3.2 Third part autorisation 22

2.3.3 Environnement de test 23

2.3.4 Données à stocker cote partenaire 23

3. ANNEXES 24

3.1

Détail des états de transaction 24

3.2

Codes erreur 26

3.3

Process de configuration d’une 3rd part Authorisation 28

3.4

Flux de création de compte avec PayPal Express 30

3.5

Migration vers une intégration API 30

© PayPal 2009 2

Préambule – Certification PayPal

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):

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

o Expé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.
([e-mail])

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

[e-mail]

© PayPal 2009 3

Expériences de l'acheteur/du marchand

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

© PayPal 2009 4

Scénario :

Le bouton « Paiement Express PayPal » s’affichera sur la page panier d’achat du site ou sur
la page « produit »

1. Le client clique sur le bouton

2. Le client est redirigé vers le site PayPal.com. La page de connexion PayPal
s’affiche.

Une fois connecté, la page de vérification PayPal s’affiche. Là, il pourra

conserver les paramètres par défaut de son compte PayPal ou bien changer
de source d’approvisionnement et/ou d’adresse de livraison.

© PayPal 2009 5

….

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, …)

© PayPal 2009 6

À 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 2009 7

1.1.2 FLUX PAYPAL OPTION + (ECM)

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.

© PayPal 2009 8

1.1.3 FLUX PAYPAL INTEGRAL

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 2009 9

1.1.4 EMBARQUEMENT ACCELERE DES MARCHANDS

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 «

authorisation

PayPal.

Pour aller plus loin :

https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_AcceleratedBoarding_
Guide.pdf

» pour pouvoir profiter de l’ensemble des fonctionnalités proposées par

third part

© PayPal 2009 10

1.2 Intégration visuelle de PayPal

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.

© PayPal 2009 11

1.2.2 COMMENT PRESENTER PAYPAL DANS LE BACKOFFICE

MARCHAND ?

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.

Exemple de présentation possible:

© PayPal 2009 12

2. Intégration technique des solutions PayPal

PayPal propose des APIs pour le PHP, l'ASP, le .net et le java en fonction de vos besoins. Il
est possible d’utiliser les API en SOAP et en NVP

Vous trouverez plus d’information ainsi que des exemples de codes source sur :

http://www.paypal.fr/fr_FR/html/Espace-Integration-PayPal/ic_api-reference.html

2.1 Appels API

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

2.1.1.1 PayPal Express (ECS)

Merchant SitePayPal Site

© PayPal 2009 13

2.1.1.2 PayPal Option + (ECM)

2.1.2 SETEXPRESSCHECKOUT (SETEC)

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.

© PayPal 2009 14

CURRENCYCODE CURRENCYCODE Code devise à trois caractères

Votre numéro de facture ou de suivi personnel. Par

INVNUM

INVOICEID

champ doit être unique pour chaque transaction

défaut, ce

DESC

Intégration NVP

ADDRESS OVERRIDE

ORDERDESCRIPTION Description des achats du client

2.1.2.2 Variables supplémentaires à retourner en intégration de

PayPal en option + ou Intégral.

Intégration SOAP

ADDRESSOVERRIDE

Champs indiquant que l'acheteur ne doit pas être

autorisé à changer l'adresse de livraison. Ne doit être

utilisé que lorsqu'une valeur ShipToAddress est

passée dans cette requête La valeur 1 indique que les

pages de PayPal doivent afficher l’adresse de

livraison que vous avez définie dans la requête

SetExpressCheckout, et non celle enregistrée chez

PayPal pour ce client.

Description

Drapeau indiquant que la section Adresse de

NO SHIPPING

EMAIL

SHIPTONAME

NOSHIPPING

BUYEREMAIL

NAME

livraison de la page de vérification PayPal ne

s'affichera pas sur le navigateur du client. Utilisez ce

drapeau si vous ne voulez pas envoyer l'adresse de

livraison à PayPal

Adresse email de l’acheteur

Nom de la personne associée à cette adresse de

livraison

© PayPal 2009 15

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOSTATE

SHIPTOCOUNTRYCODE

SHIPTOZIP

SHIPTOCITY

SHIPTOPHONENUM

STREET1

STREET2

STATEORPROVINCE

COUNTRY

POSTALCODE

CITYNAME

PHONE

Première ligne d’adresse

Seconde ligne d’adresse

Etat ou province

Code Pays

Code postal

Nom de la ville

Numéro de téléphone

L'appel SetEc retourne un jeton de session qui peut être utilisé pour rediriger le client vers
PayPal. Par défaut, sa durée de vie est de 3 heures.

Pour aller plus loin : https://cms.PayPal.com/us/cgi-bin/?cmd=_render-

content&content_ID=developer/e_howto_api_nvp_r_SetExpressCheckout

2.1.3 URL DE REDIRECTION

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

© PayPal 2009 16

- 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 » :

https://www.PayPal.com/cgi-bin/webscr?cmd=_expresscheckout&
token=value_from_SetExpressCheckoutResponse

Exemple d’URL de redirection avec bouton « Payer »

https://www.PayPal.com/cgi-bin/webscr?cmd=_expresscheckout&
token=value_from_SetExpressCheckoutResponse&useraction=commit

2.1.4 GETEXPRESSCHECKOUT (GETEC)

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

Pour aller plus loin

https://cms.PayPal.com/us/cgi-bin/?cmd=_render­content&content_ID=developer/e_howto_api_nvp_r_GetExpressCheckoutDetails

:

2.1.5 DOEXPRESSCHECKOUT (DOEC)

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.

© PayPal 2009 17

Intégration NVP

TOKEN

PAYER ID

PAYMENT ACTION

INVNUM

BUTTONSOURCE

Intégration SOAP

TOKEN

PAYERID

PAYMENTACTION

INVOICEID

BUTTONSOURCE

Description

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.

([e-mail])

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.

© PayPal 2009 18

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-

content&content_ID=developer/e_howto_api_nvp_r_DoExpressCheckoutPayment

2.2 Traitement de la transaction PayPal

2.2.1 PAIEMENTS EN ATTENTE

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 :

Authorization le paiement a été effectué en mode autorisation et n’a pas

encore été capturé.

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é

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.

Order le paiement a été effectué en mode order et n’a pas encore

été capturé ou autorisé.

Paymentreview Cette 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.

© PayPal 2009 19

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

Pour aller plus loin :

https://cms.paypal.com/cms_content/US/en_US/files/developer/IPNGuide.pdf

2.2.3 REMBOURSEMENTS

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.

© PayPal 2009 20

2.3 Détails d’intégration

2.3.1 INFORMATIONS D'AUTHENTIFICATION API

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 :

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

© PayPal 2009 21

IMPORTANT : Pour des raisons de sécurité, nous recommandons fortement
l’utilisation du certificat.

Informations d'authentification nécessaires à l’utilisation des API:

Paramètre

USER Obligatoire

PWD Obligatoire

VERSION Obligatoire

SIGNATURE Optionnel

SUBJECT Optionnel

Pour aller plus loin :

http://www.PayPal.com/IntegrationCenter/ic_certificate.html

Optionnel ou

Obligatoire

Description / Valeur

Le champ « Username » de vos paramètres

d’authentification.

Le champ « Userpassword » de vos

paramètres d’authentification

Version d’API : 59.0

Le champ « Signature » de vos paramètres

d’authentification

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 2009 22

2.3.3 ENVIRONNEMENT DE TEST

Afin de tester votre intégration, vous pouvez utiliser notre plate-forme de tests(Sandbox)
sur le lien suivant :

https://developer.PayPal.com

Vous devrez ouvrir un compte développeur puis vous pourrez ouvrir des comptes fictifs
PayPal afin de réaliser vos tests

Pour aller plus loin :

https://www.PayPal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf

2.3.4 DONNEES A STOCKER COTE PARTENAIRE

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.

© PayPal 2009 23

3. Annexes

3.1 Détail des états de transaction

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

• Processed: Un paiement a été accepté



Partially-Refunded



Refunded



Completed



Denied



Failed

© PayPal 2009 24

Pending Reasons:



none: Aucune raison spécifiée..



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

© PayPal 2009 25

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:

bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_errorcodes

© PayPal 2009 26

https://cms.PayPal.com/us/cgi-

Voici une mise en avant de quelque-uns des codes erreurs des API les plus importants:

PayPal API

SetExpressCheckout

GetExpressCheckoutDet
ails

DoExpressCheckoutPay
ment

Error

Code

10004,
10007,
104xx,
105xx,
107xx,
11601,
11602

10001,
10102,
10103,
11547

10004,
10007,
104xx

10001 Retry

10417
10422

10004,
10007,

All other
104xx,
105xx,
107xx

Fix / Escalate

Retry

Fix / Escalate

Message

Fix / Escalate

Action

DoAuthorisation and
DoCapture

DoRefund

10001,
10445

10009
10603
10606
10626

All other
106**

10001
10607
10628

10007
10009
10011

10001

Retry the API call

Retry / Message

Fix / Escalate

Retry

Fix / Escalate

Retry

© PayPal 2009 27

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

© PayPal 2009 28

Note : Le nom de l’utilisateur API est

 La page suivant s’affiche, cliquez sur Fournir les droits d’accès API

 La page suivante s’affiche. Dans le champ nom d’utilisateur API, saisissez :

« APIUSERNAME_apiPartenaire.com » et cochez les cases X (A définir).

celui de votre signature ou certificat
que vous aurez généré pour réaliser
vos développements

Important : Il est Important de faire
cocher au marchand final l’ensemble
des niveaux correspondants aux
appels API que réalisera votre
application.

 Valider l’opération en cliquant sur Soumettre.

 Votre compte PayPal est dès à présent configuré. Vous devez contacter votre conseiller PARTENAIRE

pour activer le moyen de paiement et implémenter PayPal sur votre boutique.

© PayPal 2009 29

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

© PayPal 2009 30