PAYPAL Partenaires - 2009 User Manual [fr]

Page 1
Présentation et
cadrage des solutions partenaires.
Version 1.0 – September 2009
Page 2
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
Page 3
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. (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 à
partenaires@paypal.com
© PayPal 2009 3
Page 4
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
Page 5
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
Page 6
….
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
Page 7
À 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
Page 8
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
Page 9
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
Page 10
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
Page 11
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
Page 12
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
Page 13
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
Page 14
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
Page 15
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
Page 16
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
Page 17
- 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
Page 18
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.
(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.
© PayPal 2009 18
Page 19
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
Page 20
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
Page 21
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
Page 22
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
Page 23
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
Page 24
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
Page 25
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
Page 26
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-
Page 27
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
Page 28
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
Page 29
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
Page 30
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
Loading...