PAYPAL NVP API - 2007, NVP API - 2012 User Manual [fr]

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Référence : 100018.en_US-20070524

© 2007 PayPal, Inc. Tous droits réservés. PayPal et le logo P ayPal sont des marques déposées de PayPal, Inc. Les autres marques et marques commerciales mentionnées appartiennent à leurs propriétaires respectifs. Les informations contenues dans ce document sont la propriété de PayPal, Inc. et ne peuvent être utilisées, reproduites ni diffusées sans l'autorisation écrite de PayPal, Inc. PayPal Europe Limited est autorisée et réglementée par la Financial Services Authority (FSA) du Royaume-Uni en tant qu'institution émettrice de monnaie électronique. Numéro de registre FSA de PayPal : 226056.

Avis de non responsabilité : PayPal, Inc. fournit les informations de ce manuel en l'état. PayPal, Inc. ne fournit de quelque manière que ce soit (expresse, tacite ou légale) aucune garantie résultant de ces informations. PayPal, Inc. n'assume aucune responsabilité en cas d'erreurs ou d 'omissions pour tous dommages (directs ou indirects), résultant de l'utilisation de ce manuel ou des informations qu'il contient ou résultant de l'application ou de l'utilisation du produit ou du service décrit dans ce document. PayPal, Inc. se réserve le droit de modifier les informations de ce manuel sans préavis. PayPal, Inc. ne garantit pas que les fonctionnalités décrites dans ce manuel seront annoncées ou mises à disposition de tous à l'avenir.

Mai 2007 3

4 Mai 2007

Sommaire

Sommaire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

A propos de ce document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Public ciblé. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Problèmes relatifs à la documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Historique des révisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapitre 1 Présentation . . . . . . . . . . . . . . . . . . . . . . . . .13

Présentation de l'API NVP PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Intégrer avec l'API PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Etapes de base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Créer une application Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Obtenir des informations d'authentification API . . . . . . . . . . . . . . . . . . . . . 14

Créer et envoyer la requête . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Interpréter la réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Transférer votre application dans l'e nvironnement de production de PayPal . . . . . . . . 15

Créer un compte Business PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Créer des informations d'authentification API . . . . . . . . . . . . . . . . . . . . . . 16

Modifier votre code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Détails techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Modèle de requête-réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Format de la requête. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Format de la réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Envois utilisant HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapitre 2 Accepter PayPal dans la fonction Paiement express . . . . 23

Procédure de paiement de base via PayPal . . . . . . . . . . . . . . . . . . . . . . . . . 23

1. Initialiser le paiement à l'aide de SetExpressCheckout . . . . . . . . . . . . . . . . 24

2. Rediriger le navigateur du client vers la page de connexion à PayPal . . . . . . . . 24

3. Récupérer les informations du client à l'aide de GetExpressCheckoutDetails . . . . 25

4. Effectuer une vente à l'aide de DoExpressCheckoutPayment . . . . . . . . . . . . 25

Vérifier l'adresse de livraison à l'aide de SetExpressCheckout . . . . . . . . . . . . . . . 26

Exiger une adresse confirmée. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Supprimer l'affichage de l'adresse de livraison sur PayPal . . . . . . . . . . . . . . . 27

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 5

Sommaire

Ignorer l'adresse de livraison enregistrée auprès de PayPal . . . . . . . . . . . . . . 27

Changer la langue de la page de connexion à PayPal à l'aide de SetExpressCheckout . . 28

Modifier le Logo des pages PayPal à l'aide de SetExpressCheckout . . . . . . . . . . . . 28

Sélectionner un style de pages de paiement prédéfini . . . . . . . . . . . . . . . . . 29

Spécifier les paramètres du Logo et des couleurs individuellement. . . . . . . . . . . 29

Remplir le formulaire de votre page de vérification de paiement à l'aide de

GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Effectuer une vente à l'aide de DoExpressCheckoutPayment. . . . . . . . . . . . . . . . 31

Autoriser une collecte unique à l'aide de SetExpressCheckout et de

DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Autoriser des collectes multiples à l'aide de SetExpressCheckout et de

DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Changer l'URL de la Notification instantanée de paiement (IPN) à l'aide de

DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Inclure le détail des objets à l'aide de DoExpressCheckoutPayment . . . . . . . . . . . . 33

Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment . . . . . . . . . . . . . . 34

Mettre à jour les détails de la commande à l'aide de DoExpressCheckoutPayment . . . . 35

Mettre à jour l'adresse de livraison à l'aide de DoExpressCheckoutPayment . . . . . . . . 35

Chapitre 3 Comment utiliser l'API Paiements récurrents . . . . . . . . 37

Présentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Limites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Créer un paiement récurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Procédure de création des paiements récurrents . . . . . . . . . . . . . . . . . . . . . . 40

Lancer la procédure à l'aide de SetCustomerBillingAgreement . . . . . . . . . . . . . . . 40

Spécifier un style de page de paiement personnalisé . . . . . . . . . . . . . . . . . . . . 41

Personnaliser le logo et les couleurs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Rediriger le navigateur du client vers PayPal . . . . . . . . . . . . . . . . . . . . . . . . 42

Obtenir les informations du payeur à l'aide de GetBillingAgreementCustomerDetails. . . . 43

Effectuer la transaction à l'aide de CreateRecurringPaymentsProfile . . . . . . . . . . . . 43

Effectuer la transaction à l'aide de CreateRecurringPaymentsProfile . . . . . . . . . . . . 45

Récapitulatif des Préférences de paiements récurrents . . . . . . . . . . . . . . . . . . . 46

Chapitre 4 Fonctions de gestion . . . . . . . . . . . . . . . . . . . .49

Collecter, Autoriser, Annuler et Demander une nouvelle autorisation . . . . . . . . . . . . 49

Effectuer une collecte unique dans une commande à l'aide de DoCapture . . . . . . . . . 49

Effectuer plusieurs collectes partielles dans une commande à l'aide de DoCapture . . . . 50

6 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Insérer un numéro de facture et une remarque lors de la collecte à l'aide de DoCapture. . 51

Effectuer un remboursement à l'aide de RefundTransaction . . . . . . . . . . . . . . . . 51

Remboursement intégral. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Remboursements partiels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Insérer une remarque lors du remboursement . . . . . . . . . . . . . . . . . . . . . 52

Rechercher une transaction à l'aide de TransactionSearch . . . . . . . . . . . . . . . . . 52

Visualiser les détails d'une seule transaction à l'aide de GetTransactionDetails . . . . . . 53

Annexe A Liste de référence des méthodes et des champs

de l'API NVP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Caractéristiques générales des requêtes et des paramètres . . . . . . . . . . . . . . . . 55

Paramètres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Champs multi-valeurs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Devises acceptées par PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Paiement express PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Requête SetExpressCheckout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Réponse SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Requête GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Réponse GetExpressCheckoutDetails. . . . . . . . . . . . . . . . . . . . . . . . . . 66

Requête DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . 67

Réponse DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . 71

Autorisation et collecte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

DoReauthorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

DoVoid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Sommaire

RefundTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

TransactionSearch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Paiement groupé. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Paiements récurrents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

SetCustomerBillingAgreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . . . . . . . . 94

CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Transactions de référence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

DoReferenceTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 7

Sommaire

Annexe B Liste de référence des messages d'erreur . . . . . . . . 105

Format des réponses d'erreur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Erreurs de validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Erreurs d'API générales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

Erreurs de l'API Paiement express PayPal . . . . . . . . . . . . . . . . . . . . . . . . .110

Erreurs de l'API Autorisation et collecte . . . . . . . . . . . . . . . . . . . . . . . . . . .128

Erreurs de l'API RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Erreurs de l'API TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Erreurs de l'API GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Erreurs de l'API MassPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Erreurs de l'API Paiements récurrents. . . . . . . . . . . . . . . . . . . . . . . . . . . .142

Erreurs SetCustomerBillingAgreement . . . . . . . . . . . . . . . . . . . . . . . . .142

Erreurs de GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . .143

Erreurs de CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . .144

Transactions de référence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Annexe C Exemples Web de l'API NVP. . . . . . . . . . . . . . . . 151

Descriptions des exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Accepter PayPal avec Paiement express . . . . . . . . . . . . . . . . . . . . . . . .151

Recueillir les détails de la transaction . . . . . . . . . . . . . . . . . . . . . . . . . .154

Fichiers communs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

Exemple d'utilisateur API avec signature API . . . . . . . . . . . . . . . . . . . . . . . .155

Exemples utilisant ASP classique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Télécharger et décompresser les exemples. . . . . . . . . . . . . . . . . . . . . . .156

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Exemples utilisant PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Télécharger et décompresser les exemples. . . . . . . . . . . . . . . . . . . . . . .157

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Exemples utilisant ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

Télécharger et décompresser les exemples. . . . . . . . . . . . . . . . . . . . . . .158

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

8 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Sommaire

Annexe D Le kit de développement PayPal Java. . . . . . . . . . . 159

Installation du kit de développement PayPal Java. . . . . . . . . . . . . . . . . . . . . .159

Normes prises en charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

Configuration matérielle recommandée . . . . . . . . . . . . . . . . . . . . . . . . .159

Télécharger et décompresser le kit de développement PayPal . . . . . . . . . . . . .160

Configuration post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Documentation complète du kit de développement PayPal et des classes d'API . . . . . .161

Journaux du kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . . .161

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Aperçu des classes liées aux préférences. . . . . . . . . . . . . . . . . . . . . . . .163

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164

Exemple d'utilisateur API avec signature API . . . . . . . . . . . . . . . . . . . . . .164

Exemple d'utilisateur API avec certificat d'API. . . . . . . . . . . . . . . . . . . . . .165

Annexe E Le kit de d éveloppement PayPal ASP.NET . . . . . . . . 167

Installation du kit de développement PayPal ASP.NET . . . . . . . . . . . . . . . . . . .167

Normes prises en charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

Configuration post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

Configurations personnalisées facultatives de Web.config . . . . . . . . . . . . . . .169

Journaux du kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . . .169

Activer la prise en charge des procurations . . . . . . . . . . . . . . . . . . . . . . .171

Désinstaller le kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . .171

Documentation complète du kit de développement PayPal et des classes d'API . . . . . .171

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Aperçu des classes liées aux préférences. . . . . . . . . . . . . . . . . . . . . . . .172

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Exemple d'utilisateur API avec signature API . . . . . . . . . . . . . . . . . . . . . . . .173

Exemple d'utilisateur API avec certificat d'API. . . . . . . . . . . . . . . . . . . . . . . .174

Installer les exemples sur Microsoft IIS . . . . . . . . . . . . . . . . . . . . . . . . . . .175

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

Annexe F Codes pays . . . . . . . . . . . . . . . . . . . . . . . . 177

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 9

Sommaire

10 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Préface

A propos de ce document

Le Guide de développement et référence de l'API Pair e Nom-Valeur (NVP) décrit l'API Paires Nom-Valeur de PayPal.

Public ciblé

Le Guide de développement et référence de l'API Paire Nom-Valeur (NVP) s'adresse aux développeurs de sites mettant en oeuvre des solutions utilisant l'API Paire Nom-Valeur.

Problèmes relatifs à la documentation

Si vous relevez des erreurs ou si vous rencontrez des problèmes liés à cette documentation, envoyez-nous un email en suivant les instructions ci-dessous. Décrivez l'erreur ou le problème aussi précisément que possible et communiquez-nous le titre du document et le(s) numéro(s) de page(s).

Pour contacter le service d'assistance des développeurs au sujet des problèmes liés à la documentation :

Connectez-vous à votre compte à l'adresse email et votre mot de passe dans la zone Log In.

Cliquez sur Help Center en haut à droite de la page. Cliquez sur Email PayPal Technical Support. Complétez le formulaire.

https://developer.paypal.com/ en entrant votre adresse

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 11

Historique des révisions

Historique des révisions du Guide de développement et référence de l'API Paire Nom-Valeur (NVP) .

TABLEAU P.1 Historique des révisions

Date Description

Avril 20 07 Ajout d'API pour les paiements récurrents :

SetCustomerBillingAgreement, GetBillingAgreementCustomerDeta ils et CreateRecurringPaymentsProfile.

Février 2007 La correction de problèmes comprenant la mise à jour des détails des objets pour

le paiement direct et les API Paiement express, la définition de quelques paramètres sur facultatif dans DoDirectPayment, l'ajout de SHIPTOCOUNTRYCODE, ainsi que celui de codes Switch/Solo codes pour AVS et

CVV2. Décembre 2006 Mises à jour des corrections de problèmes. Octobre 2006 Première version publique.

12 Mai 2007Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Présentation

Ce chapitre présente l'API Paire Nom-Valeur (NVP) PayPal. Il se compose des sections suivantes :

z Présentation de l'API NVP PayPal z Etapes de base z Transférer votre application dans l'environnement de production de PayPal z Détails techniques

Présentation de l'API NVP PayPal

L'API NVP PayPal est une interface de programmation simple qui vous permet à vous, le marchand, d'accéder à la fonctionalité commerciale de PayPal afin de :

z Accepter PayPal comme option de paiement sur votre site par le biais de la fonction

Paiement express.

z Collecter les paiements précédemment autorisés via Paiement express, Paiement direct ou

Paiements sur site marchand.

z Autoriser à nouveau ou annuler des autorisations antérieures. z Payer un ou plusieurs destinataires en utilisant le paiement groupé. z Effectuer des remboursements intégraux ou plusieurs remboursement partiels. z Rechercher des transactions en utilisant la date à laquelle elles ont débuté ou tout autre

critère.

z Connaitre les détails d'une transaction spécifique

Ajouter PayPal à votre application Web est aisé, grâce à L'API NVP PayPal. Il vous suffit de construire une chaîne NVP et de l'envoyer au serveur PayPal en utilisant le protocole HTTPS. PayPal vous envoie une réponse au format NVP.

Intégrer avec l'API PayPal

Vous pouvez développer avec l'API NVP PayPal en utilisant l'une ou l'autre des deux approches suivantes :

Intégration directe

L'intégration avec l'API NVP PayPal peut se faire directement par l'intermédiaire du langage de programmation de votre choix. Cette approche est la plus directe et la plus flexible. Des

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 13

Présentation

Etapes de base

exemples Web sont téléchargeables, qui vous montrent comment intégrer directement en utilisant ASP classique, PHP et ColdFusion.

Pour en savoir plus, consultez l'Annexe C, «Exemples Web de l'API NVP».

Intégrer à l'aide d'un kit de développement PayPal (SDK)

L'intégration avec l'API NVP peut se faire en utilisant un kit de développement PayPal (SDK). Les kits de développement sont fournis pour Java et ASP.NET. Ils décrivent des fonctions simples qui facilitent l'intégration avec l'API NVP.

Pour obtenir plus de détails au sujet du kit de développement PayPal, consultez l'Annexe D,

«Le kit de développement PayPal Java» ou l'Annexe E, «Le kit de développement PayPal ASP.NET».

Etapes de base

Cette section décrit les étapes de base de la programmation avec l'API NVP PayPal. Lors du développement d'une application, cette dernière communique avec l'Environnement

de test de PayPal. Dans la section suivante, « Transférer votre application dans

l'environnement de production de PayPal » page 15, nous expliquons comment transférer

votre application de l'Environnement de test à l'environnement réel de PayPal.

REMARQUE : la meilleure façon de démarrer est de télécharger et de tester les exemples

d'applications de la façon décrite dans la section « Intégrer avec l'API PayPal »

page 13.

Créer une application Web

Votre intégration de l'API NVP s'exécute habituellement dans une application Web. Vous pouvez soit concevoir votre propre application, soit utiliser un des exemples comme point de départ.

Obtenir des informations d'authentification API

Pour accéder à l'API PayPal, il est nécessaire de détenir des informations d'authentification API qui permettent de vous identifier, que ce soit une signature API ou un certificat d'API.

Utilisez l'exemple de signature et de mot de passe API suivant dans vos échantillons de programmes s'exécutant dans l'Environnement de test PayPal.

REMARQUE : si vous vous servez des exemples, cette signature est déjà présente dans le

code.

TABLEAU 1.1 Détails de l'exemple de signature API

Identifiant API sdk-three_api1.sdk.com

14 Mai 2007 Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Présentation

Transférer votre application dans l'environnement de production de PayPal

ABLEAU 1.1 Détails de l'exemple de signature API (suite)

Mot de passe API QFZCWN5HZM8VBG7Q Signature API A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ 92FRP5dqBzVesOkzbd UONzmOU

Créer et envoyer la requête

Créez une chaîne de requête NVP et l'envoyer à l'Environnement de test PayPal. Ajoutez un code à votre application Web pour pouvoir effectuer les tâches suivantes :

1. Encodez au format URL les paramètres nom et valeur dans la requête pour faire en sorte

que tous les caractères soient transmis correctement. Cette action est décrite dans la section

« Encodage dans l'URL » page 17.

2. Construisez la chaîne de requête API NVP en vous aidant des conseils de la section

« Format de la requête » page 18. Le format NVP est décrit dans la section «Format NVP » page 16.

3. Envoyez ensuite la requête NVP à l'Environnement de test PayPal ainsi qu'expliqué dans la

section « Envois utilisant HTTPS » page 20.

Interpréter la réponse

PayPal traite votre requête et vous envoie une réponse au format NVP. Ajoutez un code à votre application Web pour pouvoir effectuer les tâches suivantes :

1. Recevez la réponse HTTP et procédez à l'extraction de la chaîne NVP.

2. Décodez les valeurs des paramètres du format URL en vous aidant des conseils de la

section « Encodage dans l'URL » page 17.

3. Prenez les mesures adaptées en fonction des réponses.

Transférer votre application dans l'environnement de

production de PayPal

Une fois le codage de votre application et les tests terminés, déployez votre application dans le serveur de l'environnement de production de PayPal par le biais de votre compte Business PayPal et grâce aux informations d'authentification de ce compte.

Créer un compte Business PayPal

Lorsque vous êtes prêt à transférer votre application sur le serveur réel de PayPal, ouvrez un compte Business PayPal sur

www.paypal.fr.

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 15

Présentation

Détails techniques

Créer des informations d'authentification API

Pour utiliser les API, vous devez posséder un ensemble d'informations d'authentification pour pouvoir vous identifier auprès de PayPal. Crée r une signature API pour votre compte Business

IMPORTANT : si vous utilisez une signature API, vous devez en protéger les valeurs dans

votre intégration. Nous vous conseillons de sauvegarder ces valeurs dans un endroit sûr autre que la racine des documents de votre serveur Web. Pensez également à définir les droits d'accès à ce fichier, de sorte que seul l'utilisateur système exécutant votre application de commerce électronique puisse y accéder.

L'exemple de code ne sauvegarde pas ces valeurs de manière sûre. Il ne

devrait en aucun cas être utilisé dans un environnement de production.

REMARQUE : nous vous recommandons de vous procurer une signature API, mais vous

pouvez également utiliser un certificat d'API.

Modifier votre code

Dans votre application et pour les éléments suivants, substituez les valeurs de l'Environnement de test à celles du serveur PayPal réel :

z L'adresse du serveur dans l'URL (consultez la section « Envois utilisant HTTPS »

page 20).

z Informations d'authentification API que vous avez créées à la section « Créer des

informations d'authentification API » page 16.

Détails techniques

Cette section présente des détails techniques sur les technologies utilisées par l'API NVP PayPal.

Modèle de requête-réponse

Dans votre utilisation de l'API NVP PayPal, vous envoyez une requête NVP à PayPal et PayPal vous envoie une réponse NVP.

Format URL

La requête et la réponse sont encodées au format URL qui est défini par le Worldwide Web Consortium (W3C). L'URL est une des spécifications de l'URI. Pour obtenir plus d'informations sur l'URI, rendez-vous à l'adresse

http://www.w3.org/Addressing/.

Format NVP

NVP est une façon de spécifier des noms et des valeurs dans une chaîne. NVP est le nom non officiel de la demande dans la spécification URI. La chaîne NVP est ajoutée à l'URL.

16 Mai 2007 Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Présentation

Détails techniques

Une chaîne NVP doit se conformer aux directives suivantes :

z Le nom est séparé de la valeur par un signe égal (=). Par exemple :

FIRSTNAME=Robert

z Les paires nom-valeurs sont séparées par une esperluette (&). Par exemple :

FIRSTNAME=Robert&MIDDLENAME=He rbert&LASTNAME=Moo re

z La chaîne NVP est encodée dans l'URL.

Encodage dans l'URL

La requête et la réponse sont encodées dans l'URL. L'encodage URL garantie la transmission des caractères spéciaux, caractères qui ne sont pas autorisés dans une URL et des caractères ayant une signification particulière dans une URL tels que le signe égal et l'esperluette. Par exemple, la chaîne NVP suivante :

NAME=Robert Moore&COMPANY=R. H . Moore & Associat es

est encodée dans une URL de la manière suivante :

NAME=Robert+Moore&COMPANY=R%2E +H%2E+Moore+%26+As sociates

Utilisez les méthodes suivantes pour l'encodage dans une URL ou le décodage depuis une URL de votre chaîne NVP :

TABLEAU 1.2 Méthodes d'encodage dans une URL

Langage Méthode

ASP.NET Encode System.Web.HttpUtility.UrlEncode (buffer,

Encoding.Default)

Décodage System.Web.HttpUtility.UrlDecode (buffer,

Encoding.Default)

ASP classique

Java Encode java.net.UR LEncoder.encode

PHP Encode urlencode()

ColdFusion Encode URLEncodedF ormatstring [, charset ]

Encode Server.U RLEncode

Décodage Aucune fonction intégrée. Plusieurs exemples d'intégration sont disponibles

sur Internet.

Décodage java.net.URLDecoder.decode

Décodage urldecode()

Décodage URLDecodeurlEncodedString[, char set])

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 17

Présentation

Détails techniques

Format de la requête

Chaque requête NVP est composée de paramètres nécessaires et facultatifs et de leurs valeurs. Les noms des paramètres ne différencient pas les majuscules/minuscules. Dans les exemples contenus dans ce document, les noms des paramètres sont en MAJUSCULES et les paramètres sont divisés en deux catégories : paramètres de sécurité et paramètres du corps de la requête.

TABLEAU 1.3 Format général d'une requête

Paramètres de sécurité obligatoires

Paramètres de corps

USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature &SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.3

Les paramètres suivants sont toujours obligatoires :

USER PWD VERSION=2.3

EMARQUE : les paramètres de sécurité obligatoires apparaissent dans les

exemples sous la forme suivante :

[paramètresDeSécuritéRequis]

&METHOD=methodName&otherRequiredAndOptionalParameters

Dans la pratique, il est nécessaire d'enchaîner tous les paramètres et toutes les valeurs dans une chaîne unique , encodée au format URL. Après le paramètre METHODE, vous pouvez spécifier les paramètres dans l'ordre de votre choix.

Paramètres de sécurité obligatoires

Les paramètres de sécurité obligatoires sont décrits ci-dessous. Ils correspondent à vos informations d'authentification API PayPal.

TABLEAU 1.4 Paramètres de sécurité obligatoires :

Informations d'authentification API

Paramètre Valeur

USER Obligatoire Votre identifiant API PayPal. PWD Obligatoire Votre mot de passe API PayPal. VERSION=2.3 Obligatoire Le numéro de version du service API NVP. SIGNATURE Facultatif Votre chaîne de signature API PayPal.

Il n'est pas nécessaire d'inclure ce paramètre si vous utilisez un certificat d'API.

SUBJECT Facultatif L'adresse email du compte PayPal qui vous a autorisé à faire cet appel.

Définissez ce paramètre seulement si vous appelez une API pour le compte d'un autre utilisateur.

18 Mai 2007 Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Présentation

Détails techniques

IMPORTANT : vous devez protéger les valeurs de USER, PWD et de SIGNATURE dans

L'exemple de code ne sauvegarde pas ces valeurs de manière sûre. Il ne devrait en aucun cas être utilisé dans un environnement de production.

Des exemples de code se trouvent peut-être là où ces valeurs sont stockées, sous un format HTML. L'exemple suivant montre ce que vous devriez EVITER de faire dans un Environnement de production :

Paramètres API

Le corps de la requête doit contenir le nom de la méthode API dans le paramètre METHODE. En outre, chaque méthode nécessite des paramètres obligatoires et facultatifs :

METHOD=methodName&requiredAndO ptionalParameters

Toutes les méthodes d'API et leurs paramètres sont detaillés dans l'Annexe A, «Liste de

référence des méthodes et des champs de l'API NVP». Des exemples d'utilisation sont

présentés aux Chapitre 2, « Débiter une carte bancaire en utilisant DoDirectPayment»,

Chapitre 2, « Accepter PayPal dans la fonction Paiement express», et Chapitre 4, « Fonctions de gestion».

Format de la réponse

Une réponse en provenance des serveurs PayPal consiste en une chaîne de paires nom-valeur encodée au format URL, à l'instar de la requête, si ce n'est qu'elle se présente sous le format général suivant :

TABLEAU 1.5 Format genéral d'une réponse indiquant un e réuss ite

Champs d'une réponse indiquant une réussite

ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber

L'en-tête de la réponse de réussite apparaît dans les exemples sous la forme suivante :

[champsDeRéponseRéussie]

Champs de la réponse API

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 19

&NAME1=value1&NAME2=value2&NAME3=value3&...

Présentation

Détails techniques

Chaque réponse comprend le champ ACK. Si la valeur du champ est Success ou SuccessWithWarning, il vous faut alors traiter les champs de la réponse API. Dans le cas d'une réponse indiquant une réussite, vous pouvez ignorer tous les champs jusqu'au et y compris le champ BUILD. Les champs d'importance se trouve après le champ BUILD.

Les champs susceptibles de se trouver dans une réponse de réussite sont détaillés pour chaque méthode dans l'Annexe A, «Liste de référence des méthodes et des champs de l'API NVP». Les actions que vous prenez en ce qui concerne les champs dépendent du mode API spécifique que vous appelez, par exemple Remplir un formulaire FORM pour votre utilisateur, mettre à jour votre base de données, etc.

Réponses d'erreur

Si la valeur ACK est Erreur ou Avertissement, les champs de réponse API ne sont pas renvoyés. Une réponse d'erreur se présente sous le format général suivant.

TABLEAU 1.6 Format d'une réponse d'erreur

Champs de la réponse sur l'erreur

ACK=Error&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=2.300000& BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage L_LONGMESSAGE0=longMessage &L_SEVERITYCODE0=severityCode

Il est possible que des erreurs multiples soient renvoyées. Chaque groupe d'erreur est caractérisé par un suffixe numérique différent, en commençant par 0 et incrémenté d'une unité à chaque erreur.

Pour connaitre les causes possibles des erreurs et savoir comment les corriger, reportez-vous à l'explication du code spécifique de l'erreur, son message court et son message long dans l'Annexe B, «Liste de référe nce des messages d'erreur».

Valeurs du paramètre ACK

Le tableau ci-dessous répertorie les valeurs du paramètre ACK.

ABLEAU 1.7 Valeurs du paramètre ACK

Type de réponse Valeur

Réponse de réussite Success

SuccessWithWarning

Réponse d'erreur Error

Warning

Envois utilisant HTTPS

Votre application Web envoie la chaîne NVP encodée au format URL via une connexion HTTPS à l'un des serveurs API de PayPal. PayPal fournit un serveur réel ainsi qu'un serveur

20 Mai 2007 Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Présentation

Détails techniques

en Environnement de test qui vous permet de traiter les transations dans un Environnement de test.

Serveurs API pour la sécurité des signatures API

Si vous utilisez une signature API, envoyez la requête à l'un des serveurs suivants :

Environnement de test : https: //api-3t.sandbox.paypal.com/nv p Réel: https://api-3t.paypal.com/nvp

Serveurs API garantissant la sécurité des certificats d'API

Si vous utilisez un certificat d'API, envoyez la requête à l'un des serveurs suivants :

Environnement de test : https://api.sandbox.paypal .com/nvp Réel : https://api.paypal.com/nvp

Guide de développement et référence de l'API Paire Nom-Valeur (NVP) Mai 2007 21

Présentation

Détails techniques

22 Mai 2007 Guide de développement et référence de l'API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

S'il choisit l'option Paiement express PayPal, le client économisera du temps : plusieurs étapes de la procédure de paiement seront ignorées car les informations de facturation et de livraison déjà enregistrées auprès de PayPal seront utilisées.

Cette section vous explique comment utiliser la fonction Paiement express PayPal pour accepter des paiements via PayPal. Elle se compose des rubriques suivantes :

z « Procédure de paiement de base via PayPal » page 23 z « Vérifier l'adresse de livraison à l'aide de SetExpressCheckout » page 26 z « GetExpressCheckoutDetails renvoie l'adresse de livraison ignorée » page 28 z « Modifier le Logo des pages PayPal à l'aide de SetExpressCheckout » page 28 z « Remplir le formulaire de votre page de vérification de paiement à l'aide de

GetExpressCheckoutDetails » page 30

z « Effectuer une vente à l'aide de DoExpressCheckoutPayment » page 31 z « Autoriser une collecte unique à l'aide de SetExpressCheckout et de

DoExpressCheckoutPayment » page 31

z « Autoriser des collectes multiples à l'aide de SetExpressCheckout et de

DoExpressCheckoutPayment » page 32

z « Changer l'URL de la Notification instantanée de paiement (IPN) à l'aide de

DoExpressCheckoutPayment » page 32

z « Inclure le détail des objets à l'aide de D oExpressCheckoutPayment » page 33 z « Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment » page 34 z « Mettre à jour les détails de la commande à l'aide de DoExpressCheckoutPayment »

page 35

z « Mettre à jour l'adresse de livraison à l'aide de DoExpressCheckoutPayment » page 35

Procédure de paiement de base via PayPal

Consultez le guide d'intégration de Paiement express pour obtenir des informations sur cette fonction, en particulier le flux des pages au fil de la procédure, les points d'intégration, le placement des boutons et la conception des pages.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 23

Accepter PayPal dans la fonction Paiement express

Procédure de paiement de base via PayPal

La procédure de Paiement express via PayPal doit se dérouler selon les étapes suivantes :

1. Initialiser le paiement à l'aide de SetExpressCheckout

2. Rediriger le navigateur du client vers la page de connexion à PayPal

3. Récupérer les informations du client à l'aide de GetExpressCheckoutDetails

4. Effectuer une vente à l'aide de DoExpressCheckoutPayment

La réponse SetExpressCheckout, vous fournit un TO KEN qui identifie de manière unique cette transaction en trois étapes. Vous devez transmettre ce TOKEN dans les requêtes

GetExpressCheckoutDetails et DoExpressChec koutPayment. GetExpressCheckoutDetails et DoExpressChec koutPayment renvoient toutes les

deux la valeur de TOKEN dans la réponse. Cet exemple illustre un paiement de base utilisant un nombre minimum de paramètres.

1. Initialiser le paiement à l'aide de SetExpressCheckout

Le mode de requête SetExpressCheckout indique à PayPal que vous utilisez Paiement express PayPal pour obtenir un paiement de votre client.

Vous devez toujours inclure les paramètres suivants dans la requête SetExpressCheckout :

z AMT z RETURNURL z CANCELURL

ABLEAU 2.1 Initialiser le paiement

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=SetExpressCheckout&AMT=10.00&

RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html&

[champsDeRéponseRéussie]&TOKEN=EC-3DJ78083ES565113B

REMARQUE : du fait que nous ne la spécifions pas, la valeur de l'élément P AYMENTACTION

sera sa valeur par défaut : Vente.

Sauvegardez le TOKEN en vue de son utilisation lors des appels Paiement express PayPal restants.

2. Rediriger le navigateur du client vers la page de connexion à PayPal

Lorsque vous avez reçu une réponse de SetExpressCheckout, ajoutez la valeur de TOKEN fournie dans la réponse SetExpressCheckout sous forme de paire nom-valeur à l'URL suivante et redirigez le navigateur du client vers cette URL :

https://www.paypal.com/fr/cgi- bin/webscr?cmd=_ex press-checkout& token=value_from_SetExpressChe ckoutResponse

24 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

Procédure de paiement de base via PayPal

Pour rediriger le navigateur d'un client vers la page de connexion à PayPal, PayPal vous recommande d'utiliser la réponse HTTPS 302 « Objet déplacé » avec l'URL ci-dessus comme valeur de l'en-tête Location dans la réponse HTTPS. Si votre serveur utilise le protocole SSL, vous évitez que le navigateur ne reçoive des avertissements à propos d'un mélange d'images sécurisées et non sécurisées.

3. Récupérer les informations du client à l'aide de GetExpressCheckoutDetails

Le mode GetExpressCheckoutDetails renvoie les informations du client, y compris son nom et son adresse enregistrés par PayPal.

Vous devez toujours inclure les paramètres suivants dans GetExpressCheckoutDetails :

z TOKEN: utilisez la valeur fournie par la réponse SetExpressCheckout

La réponse contient ce TOKEN ainsi que les informations du client.

TABLEAU 2.2 Obtenir les informations du client

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=GetExpressCheckoutDetails&

TOKEN=EC-3DJ78083ES565113B

[champsDeRéponseRéussie]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=vérifié&FIRSTNAME=Pierre& LASTNAME=Dupont&COUNTRYCODE=FR& SHIPTONAME=Pierre Dupont&SHIPTOSTREET=by 10 rue de la République& SHIPTOCITY=Paris&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=FR& SHIPTOZIP=75015&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmé

Assurez-vous que la valeur de TOKEN corresponde à la valeur contenue dans la réponse SetExpressCheckout.

Sauvegarder PAYERID en vue de son utilisation lors du prochain appel.

4. Effectuer une vente à l'aide de DoExpressCheckoutPayment

Requête pour obtenir le paiement via la fonction <:v "Express Checkout" 1> de PayPal à l'aid de l'API DoExpressCheckoutPayment.

Par défaut, vous accomplissez la vente finale à l'aide de l'API DoExpressCheckoutPayment. Vous pouvez également demander une autorisation pour collecte ultérieure du paiement. Pour en savoir plus, reportez-vous à la section « Autoriser des collectes multiples à l'aide de

SetExpressCheckout et de DoExpressCheckoutPayment » page 32.

Vous devez toujours inclure les paramètres suivants dans la requête SetExpressCheckout TOKEN : utilisez la valeur fournie par la réponse SetExpressCheckoutDetails PAYERID : utilisez la valeur fournie par la réponse SetExpressCheckoutDetails

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 25

Accepter PayPal dans la fonction Paiement express

Vérifier l'adresse de livraison à l'aide de SetExpressCheckout

PAYMENTACTION : choisissez Vente. Il s'agit de la valeur par défaut de SetExpressCheckout.

AMT : utilisez la même valeur que pour la requêtet

TABLEAU 2.3 Effectuer une vente

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment&

TOKEN=EC-0E881823PA052770A&AMT=10.00& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale

[champsDeRéponseRéussie]&TOKEN=EC-0E881823PA052770A&

TRANSACTIONID=8SC56973LM923823H&TRANSACTIONTYPE=expresscheck out& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T20:16:05Z&AMT=10.00& CURRENCYCODE=EUR&FEEAMT=0.59&TAXAMT=0.00& PAYMENTSTATUS=Completed&PENDINGREASON=None&REASONCODE=None

Vérifier l'adresse de livraison à l'aide de SetExpressCheckout

Vous pouvez modifier le comportement de l'adresse de livraison grâce aux paramètres

REQCONFIRMSHIPPING, NOSHIPPING, et ADDROVER RIDE dans la requête SetExpressCheckout.

L'adresse de livraison est spécifiée dans les paramètres SHIPTO

Exiger une adresse confirmée

Pour exiger que l'adresse de livraison soit une adresse PayPal confirmée, donnez à REQCONFIRMSHIPPING la valeur 1 dans la requête SetExpres sCheckout.

xxx.

REMARQUE : la valeur de REQCONFIRMSHIPPING remplace le paramètre situé dans vos

Préférences de compte marchand.

ABLEAU 2.4 Exiger une adresse confirmée

Requête

Réponse

26 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

[paramètresDeSécuritéRequis]&METHOD=SetExpressCheckout&AMT=10.00&

RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html& &REQCONFIRMSHIPPING=1

[champsDeRéponseRéussie]&TOKEN=EC-0E881823PA052770A

Accepter PayPal dans la fonction Paiement express

Vérifier l'adresse de livraison à l'aide de SetExpressCheckout

Supprimer l'affichage de l'adresse de livraison sur PayPal

Pour faire en sorte que l'adresse de livraison du client ne s'affiche pas sur les pages Web de PayPal, donnez à NOSHIPPING la valeur 1 dans la requête SetExpressCheckout. Cette fonction peut être utile dans les cas où le produit ou le service que vous vendez ne nécessite pas de livraison.

TABLEAU 2.5 Supprimer l'adresse de livraison

Requête

Réponse

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails ne renvoie pas l'adresse de livraison.

TABLEAU 2.6 GetExpressCheckoutDetails

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-17C76533PL706494P

[champsDeRéponseRéussie]&TOKEN=EC17C76533PL706494P&EMAIL=abcdef@masociété.com&PAYERID=95HR9CM6D56Q2& PAYERSTATUS=vérifié&FIRSTNAME=Pierre&LASTNAME=Dupont&COUNTRYCODE=FR& ADDRESSID=PayPal&ADDRESSSTATUS=Aucun

Ignorer l'adresse de livraison enregistrée auprès de PayPal

Pour ne pas tenir compte de l'adresse de livraison enregistrée auprès de PayPal, appelez SetExpressCheckout afin de pouvoir donner à l'élémentADDROVERRIDE la valeur 1 et définissez les champs de l'adresse de livraison (consultez le Tableau A.5, « Adresse de

livraison (facultatif) »).

Si l'adresse est ignorée, le client ne peut pas la modifier.

TABLEAU 2.7 Ignorer l'adresse de livraison

Requête

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 27

[paramètresDeSécuritéRequis]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html& &SHIPTONAME=Peter+Dupont&SHIPTOSTREET=by 10 rue de la République&SHIPTOCITY=Paris &SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=99911&

ADDROVERRIDE=1

Accepter PayPal dans la fonction Paiement express

Changer la langue de la page de connexion à PayPal à l'aide de SetExpressCheckout

Réponse

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails renvoie l'adresse de livraison ignorée

TABLEAU 2.8 GetExpressCheckoutDetails

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=GetExpressCheckoutDetails&TOKEN=EC- 17C76533PL706494P

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P& PAYER=abcdef@masociété.com&PAYERID=95HR9CM6D56Q2&PAYERSTATUS=vérifié& FIRSTNAME=Pierre&LASTNAME=Dupont& COUNTRYCODE=FR&SHIPTONAME=Peter+Dupont&SHIPTOSTREET=by 10 rue de la

République& SHIPTOCITY=Paris&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=75015& ADDRESSID=PayPal&ADDRESSSTATUS=non confirmé

Changer la langue de la page de connexion à PayPal à l'aide de

SetExpressCheckout

Pour changer la langue de la page de connexion à PayPal, donner à LO CALECODE une des valeurs autorisées dans SetExpressCheckout. Pour obtenir plus d'informations au sujet des valeurs de LOCALECODE, consultez le Tableau A.4, « Paramètres de la requête

SetExpressCheckout ». Dans l'exemple su ivant nous donnons à LOCALECODE la valeur

Français.

TABLEAU 2.9 Changer la langue de la page de connexion à PayPal pour la valeur Français

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=SetExpressCheckout&AMT=10.00& CURRENCYCODE=EUR& RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html& &LOCALECODE=fr_FR

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P

Modifier le Logo des pages PayPal à l'aide de

SetExpressCheckout

Il existe deux façons de modifier le logo et d'autres paramètres de couleur sur les pages PayPal :

z en sélectionnant un style de pages de paiement prédéfini z en définissant les paramètres du logo et des couleurs individuellement

28 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

Modifier le Logo des pages PayPal à l'aide de SetExpressCheckout

Sélectionner un style de pages de paiement prédéfini

Pour spécifier un style de pages de paiement pour les pages PayPal, définissez le paramètre PAGESTYLE dans SetExpressCheckout. Définissez PAGESTYLE en sélectionnant un nom parmi les styles de page créés par vous dans vos pages de paiement personnalisées sur https://www.paypal.fr.

L'exemple suivant définit la valeur de PAGESTYLE comme DesignerFotos-Yellow dans le mode SetExpressCheckout

TABLEAU 2.10 Sélectionner un style de pages de paiement prédéfini

Requête

Réponse

PAGESTYLE=DesignerFotos-Yellow

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P

Spécifier les paramètres du Logo et des couleurs individuellement

Pour faire en sorte que les pages W eb de PayPal ressemblent à vos propres pages Web, il vous suffit de définir les paramètres suivants dans SetExpressCheckout :

z HDRIMG : spécifie l'image que vous désirez afficher en haut à gauche de la page de

paiement

z HDRBORDERCOLOR : définit la couleur de bordure de l'en-tête de la page de paiement z HDRBACKCOLOR : définit la couleur d'arrière-plan de l'en-tête de la page de paiement z PAYFLOWCOLOR : définit la couleur d'arrière-plan de la page de paiement

TABLEAU 2.11 Spécifier les paramètres du Logo et des couleurs individuellemen t

Requête

HDRIMG=https://www.masociété.com/images/HeaderImage.gif& HDRBORDERCOLOR=3366FF&HDRBACKCOLOR=D3EFF5&PAYFLOWCOLOR=F8F5F5

Réponse

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 29

[champsDeRéponseRéussie]&TOKEN=EC-17C76533PL706494P

Accepter PayPal dans la fonction Paiement express

Remplir le formulaire de votre page de vérification de paiement à l'aide de GetExpressCheckoutDetails

Remplir le formulaire de votre page de vérification de paiement

à l'aide de GetExpressCheckoutDetails

Utilisez le nom et l'adresse de livraison du payeur fournis par la réponse GetExpressCheckoutDetails pour renseigner les champs du formulaire sur la page de vérification de paiement affichée une fois le client revenu de PayPal sur votre site.

TABLEAU 2.12 Remplir le formulaire de votre page de vérification de paiement

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-3DJ78083ES565113B

[champsDeRéponseRéussie]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=vérifié&FIRSTNAME=Pierre&LASTNAME=Dupont& COUNTRYCODE=FR&SHIPTONAME=Pierre Dupont&SHIPTOSTREET=by 10 rue de la République& SHIPTOCITY=Paris&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=75015& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmé

Obtenez le nom du payeur à partir des paramètres suivants de la réponse GetExpressCheckoutDetails :

z SALUTATION z FIRSTNAME z MIDDLENAME z LASTNAME z SUFFIX

Obtenez l'adresse de livraison à partir des paramètres suivants de la réponse GetExpressCheckoutDetails :

z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM z SHIPTOZIP

30 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

Effectuer une vente à l'aide de DoExpressCheckoutPayment

Utilisez DoExpressCheckoutPayment pour effectuer une vente finale. Pour en savoir plus, reportez-vous à la section « Procédure de paiement de base via PayPal »,

page 23.

Autoriser une collecte unique à l'aide de SetExpressCheckout

et de DoExpressCheckoutPayment

Vous pouvez autoriser le paiement d'une vente finale en attribuant la valeur Authorization au champ PAYMENTACTION des API SetExpressCheckout et DoExpressCheckoutPayment.

Pour en savoir plus sur la fonction Autorisation et collecte, consultez « Effectuer une collecte

unique dans une commande à l'aide de DoCapture », page 49. Pour en savoir plus sur

Autorisation et collecte.

TABLEAU 2.13 Autoriser une collecte unique à l'aide de SetExpressCheckout

Requête

Réponse

TABLEAU 2.14 Autoriser une collecte unique à l'aide de DoExpressCheckoutPay ment

Requête

Réponse

PAYMENTACTION=Authorization

[champsDeRéponseRéussie]& TOKEN=EC-30P862430W113011F

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-30P862430W113011F&PAYERID=95HR9CM6D56Q2&AMT=10.00

PAYMENTACTION=Authorization

[champsDeRéponseRéussie]&TOKEN=EC-30P862430W113011F& TRANSACTIONID=4D479374VP578364Y&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:02:42Z&AMT=10.00& CURRENCYCODE=EUR&TAXAMT=0.00&PAYMENTSTATFR=Pending& PENDINGREASON=authorization&REASONCODE=None

Enregistrez TRANSACTIONID et utilisez-la comme valeur de AUTHORIZATIONID pour la requête DoCapture. Pour en savoir plus sur DoCapture, reportez-vous à la section « Collecter,

Autoriser, Annuler et Demander une nouvelle autorisation », page 49.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 31

Accepter PayPal dans la fonction Paiement express

Autoriser des collectes multiples à l'aide de SetExpressCheckout et de DoExpressCheckoutPayment

Autoriser des collectes multiples à l'aide de

SetExpressCheckout et de DoExpressCheckoutPayment

Vous pouvez autoriser le paiement de plusieurs collectes en attribuant la valeur Order au champ PAYMENTACTION des API SetExpressCheckout et DoExpressCheckoutPayment.

Pour en savoir plus sur la fonction Autorisation et collecte, consultez « Effectuer plusieurs

collectes partielles dans une commande à l'aide de DoCapture », page 50.

TABLEAU 2.15 Autoriser des collectes multiples à l'aide de SetExpressCh eckout

Requête

Réponse

TABLEAU 2.16 Autoriser des collectes multiples à l'aide de DoExpre ssCheck outPa yment

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=SetExpressCheckout&AMT=1.00& RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html&

PAYMENTACTION=Order

[champsDeRéponseRéussie]&TOKEN=EC-8NB10343BA3562027

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment&

TOKEN=EC-8NB10343BA3562027&PAYERID=95HR9CM6D56Q2&AMT=1.00&

PAYMENTACTION=Order

[champsDeRéponseRéussie]&TOKEN=EC-8NB10343BA3562027& TRANSACTIONID=O-2YX05090CA6454418&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=None&ORDERTIME=2006-08-22T22:22:03Z&AMT=1.00& CURRENCYCODE=EUR&TAXAMT=0.00&PAYMENTSTATUS=None&PENDINGREASON=order&

REASONCODE=None

Enregistrez TRANSACTIONID et utilisez-la comme valeur de AUTHORIZATIONID pour la requête DoCapture. Pour en savoir plus sur DoCapture, reportez-vous à la section « Collecter,

Autoriser, Annuler et Demander une nouvelle autorisation » page 49.

Changer l'URL de la Notification instantanée de paiement (IPN)

à l'aide de DoExpressCheckoutPayment

Pour changer l'URL permettant de recevoir la Notification instantanée de paiement (IPN) pour cette transaction, spécifiez le paramètre NOTIFYURL dans DoExpressCheckoutPayment.

Si vous ne spécifiez pas cette valeur dans la requête, c'est l'URL de notification de vos Préférences de marchand qui est utilisée, si elle existe.

32 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

Inclure le détail des objets à l'aide de DoExpressCheckoutPay me n t

Pour plus d’informations concernant la fonction IPN, consultez le Guide d’intégration de la gestion des commandes.

TABLEAU 2.17 Changer l'URL de la Notification instantanée de paiement (IPN)

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00& PAYMENTACTION=Sale&NOTIFYURL=https://www.masociété.com/process-ipn/

[champsDeRéponseRéussie]&TOKEN=EC-8AX1275942659774U& TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=EUR&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Inclure le détail des objets à l'aide de

DoExpressCheckoutPayment

Vous pouvez insérer des lignes de détails sur les objets en définissant les paramètres suivants pour DoExpressCheckoutPayment:

z L_NAMEn : le nom ou la description de l'objet z L_NUMBERn : le numéro de l'objet z L_QTYn : la quantité z L_TAXAMTn : le montant de la taxe pour l'objet z L_AMTn : le coût de l'objet

Vous pouvez détailler autant d'objets que vous le souhaitez. En commençant par 0, ajoutez un numéro au nom de champ et incrémentez ce numéro d'une unité pour chaque champ.

L'exemple suivant définit le détail de deux objets. Ces détails sont enregistrés par PayPal

TABLEAU 2.18 Ajouter le détail des objets

Requête

Réponse

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 33

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-4XH62109C8044521N&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24&

ITEMAMT=5.75&TAXAMT=0.49&L_NUMBER0=1&L_NAME0=A+Tale+of+Two+Cities&L_AMT0=2.50& L_QTY0=1&L_TAXAMT0=0.21&L_NAME1=Oliver+Twist&L_NUMBER1=2&L_AMT1=3.25&L_QTY1=1& L_TAXAMT1=0.28

[champsDeRéponseRéussie]&TOKEN=EC-4XH62109C8044521N& TRANSACTIONID=77U91743M2649930P&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:49:50Z&AMT=6.24& CURRENCYCODE=EUR&FEEAMT=0.48&TAXAMT=0.28&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Accepter PayPal dans la fonction Paiement express

Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment

Si vous spécifiez L_AMTn">, vous devez préciser le paramètre ITEMAMT. La somme des valeurs de L_AMT

n and L_QTYn doit être égale au ITEMAMT.

Si vous spécifiez L_TAXAMT valeurs de L_TAXAMT

n, vous devez préciser le paramètre TAXAMT. La somme des

n and L_QTYn doit être égale au TAXAMT.

Veuillez trouver ci-dessous des exemples de ITEMAMT and TAXAMT:

ITEMAMT = (L_AMT0 * L_QTY0) + (L_AMT1 + L_QTY1) + L_AMT2 TAXAMT = (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1 ) + L_TAXAMT2

REMARQUE : si la somme du détail des objets ne correspond pas au ITEMAMT ou au TAXAMT,

les détails sont rejetés et la transaction est traitée en utilisant les valeurs de

ITEMAMT or TAXAMT. La valeur ACK de la réponse est définie par SuccessWithWarning.

Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment

Si vous désirez que l'utilisateur PayPal puisse voir les sous-totaux correspondant au coût des objets, aux frais de livraison, aux frais de dossier et aux taxes, incluez les paramètres suivants pour DoExpressCheckoutPayment:

z ITEMAMT z SHIPPINGAMT z HANDLINGAMT z TAXAMT

REMARQUE : vérifiez que la somme des valeurs de ITEMAMT, SHIPPINGAMT,

HANDLINGAMT, ET TAXAMT soit égale à la valeur de AMT. Ces champs ne

peuvent pas avoir une valeur nulle et doivent tous être définis.

TABLEAU 2.19 IInclure les sous-totaux

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment TOKEN=EC-0EU150885J108392M&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24& AMT=192.22&ITEMAMT=176.02&SHIPPINGAMT=14.34&HANDLINGAMT=1.10&TAXAMT=0.76

[champsDeRéponseRéussie]&TOKEN=EC0EU150885J108392M&TRANSACTIONID=29W817045L6797418&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:20:22Z&AMT=192.22&CURRENCYCODE=EUR&FEEAMT=5.87&TAXAMT=0.76&PAYMENTSTATUS =Completed&PENDINGREASON=None&REASONCODE=None

34 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Accepter PayPal dans la fonction Paiement express

Mettre à jour les détails de la commande à l'aide de DoExpressChec ko utPayment

Mettre à jour les détails de la commande à l'aide de

DoExpressCheckoutPayment

Il est possible que vous ayez à mettre à jour le détail de la commande sur le site PayPal si le client modifie la commande lorsqu'il retourne à la page de vérification de la commande. Si une modification implique de nouvelles valeurs pour l'un des paramètres suivants, vous devez mettre à jour le détail de la commande sur le site PayPal à l'aide de l'API DoExpressCheckoutPayment:

z DESC : la description de l'objet z CUSTOM : un champ que vous pouvez utiliser librement z INVNUM : votre numéro de facture ou de suivi

Ces trois paramètres ont pu être définis pour l'API SetExpressCheckout.

TABLEAU 2.20 Mettre à jour les détails

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& DESC=Order+for+5+books&CUSTOM=Thank+you+for+your+business!&INVNUM=ABC1234567

[champsDeRéponseRéussie]&TOKEN=EC5JA9268562132991T&TRANSACTIONID=9JJ517146A732773R&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:14:54Z&AMT=10.00&CURRENCYCODE=EUR&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS= Completed&PENDINGREASON=None&REASONCODE=None

Mettre à jour l'adresse de livraison à l'aide de

DoExpressCheckoutPayment

Il est possible que vous ayez à mettre à jour l'adresse de livraison sur le site PayPal si le client modifie l'adresse de livraison lorsqu'il retourne à la page de vérification de la commande. Le cas échéant, vous devez mettre à jour l'adresse de livraison associée à cette transaction sur le site PayPal.

Vous pouvez mettre à jour l'adresse de livraison en définissant les paramètres suivants pour l'API DoExpressCheckoutPayment :

z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 35

Accepter PayPal dans la fonction Paiement express

Mettre à jour l'adresse de livraison à l'aide de DoExpressCheckoutPayment

z SHIPTOPHONENUM z SHIPTOZIP

TABLEAU 2.21 Mettre à jour l'adresse de livraison

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoExpressCheckoutPayment& METHOD=DoExpressCheckoutPayment&TOKEN=EC-47C20533CU265432F& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00&

SHIPTONAME=Michael+Brown&SHIPTOSTREET=22+First+Street&SHIPTOCITY=Chicago& SHIPTOCOUNTRYCODE=FR&SHIPTOSTATE=IL&SHIPTOZIP=60605

[champsDeRéponseRéussie]&TOKEN=EC-47C20533CU265432F& TRANSACTIONID=59L39584YA765250B&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-23T16:08:12Z&AMT=10.00& CURRENCYCODE=EUR&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

36 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Comment utiliser l'API Paiements récurrents

L'API Paiements récurrents vous permet de facturer un client pour une somme d'argent fixe selon un calendrier pré-défini. L'acheteur s'inscrit à la fonction Paiements récurrents lorsqu'il effectue un paiement sur votre site. Examinons les exemples suivants :

z Un acheteur s'abonne à une revue ou à un bulletin d'information sur votre site et accepte de

payer une somme forfaitaire mensuelle.

z Un acheteur accepte de verser une somme forfaitaire trimestrielle à un fournisseur d'accès à

Internet pour l'hébergement de son site Ces exemples présentent des transactions de paiements récurrentes et à montant fixe. L'API Paiements récurrents ne doit pas être confondue avec la fonction Abonnements et

paiements récurrents disponible pour les Paiements sur site marcha nd. Consultez les sections Abonnements et paiements récurrents de la Présentation de l'API pour plus d'informations sur ces fonctions.

Présentation

Les paiements récurrents sont créés lorsque vous appelez l'API Paiements récurrents pendant la procédure de paiement de votre site.

Lors de la création d'un paiement récurrent pour un acheteur, vous créez un profil de paiements récurrents. Un profil regroupe les informations relatives aux paiements récurrents et comprend les détails d'une période d'essai facultative et d'une période de paiement.

Chaque période contient des informations sur la fréquence et les montants des paiements, frais de livraison et taxe inclus le cas échéant.

Une fois le profil créé, PayPal y rajoute automatiquement une file de paiements en fonction de la date, de la fréquence et du montant de la facturation, jusqu'au terme du profil ou jusqu'à son annulation par le client ou le marchand.

Le client et le marchand peuvent tous deux accéder aux détails des paiements récurrents ou supprimer le profil de paiements récurrents depuis leur compte PayPal respectif. Vous pouvez consulter les rapports relatifs aux paiements récurrents via le Portail des rapports marchands de PayPal.

Limites

Les paiements récurrents utilisant l'API du même nom sont limités dans la version actuelle.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 37

Comment utiliser l'API Paiements récurrents

Limites

z Un profil ne dispose que d'une seule période d'essai et d'une seule période de paiement. z Le panier du client ne peut pas contenir à la fois des objets réglables par paiements

récurrents et d'autres réglables par paiements simultanés.

z Un seul paiement récurrent peut être créé au cours d'une procédure de paiement. z L'API Paiements récurrents ne peut pas être utilisée pour modifier ou annuler un profil de

paiements récurrents.

38 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Créer un paiement récurrent

Le schéma suivant illustre le flux type des étapes de création d'un paiement récurrent lors d'une procédure de paiement. Les étapes numérotées du schéma sont expliquées dans le

Tableau 3.1.

Comment utiliser l'API Paiements récurrents

Créer un paiement récurrent

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 39

Comment utiliser l'API Paiements récurrents

Procédure de création des paiements récurrents

TABLEAU 3.1 Procédure de création des paiements récurren ts

Etape Le marchand... PayPal...

1 Appelle SetCustomerBillingAgreement ; le type de

facturation est défini par RecurringPayment, pour initier une transaction de paiements récurrents

2 Renvoie au marchand un jeton identifiant la

transaction.

3 Redirige le navigateur du client vers :

https://www.paypal.com/cgibin/webscr?cmd=_customer-billingagreement&token=<token returned by SetCustomerBillingAgreement>

Affiche la page de connexion. Permet à l'utilisateur de modifier l'adresse de

livraison.

4 Redirige le navigateur du client vers successURL

transmise à SetCustomerBillingAgreement.

5 Appelle GetBillingAgreementCustomerDetails

pour obtenir les informations du client (facultatif).

Renvoie une réponse GetBillingAgreeementCustomerDetails.

Affiche une page de vérification à l'attention du client.

6 Appelle CreateRecurringPaymentsProfile.

Renvoie ProfileID dans la réponse CreateRecurringPaymentsProfile si la création du profil a été réussie.

7 Affiche une page de transaction réussie.

Lancer la procédure à l'aide de SetCustomerBillingAgreement

La requête SetCustomerBillingAgreement avertit PayPal que vous êtes en train d'amorçer une transaction de paiements récurrents avec votre client.

40 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Comment utiliser l'API Paiements récurrents

Spécifier un style de page de paiement personnalisé

Vous devez obligatoirement inclure les paramètres suivants dans la requête SetCustomerBillingAgreement :

z BILLINGTYPE z RETURNURL z CANCELURL

Le Tableau 3.2 illustre un exemple de requête et réponse utilisant l'API NVP pour SetCustomerBillingAgreement. La réponse SetCustomerBillingAgreement fournit un jeton qui identifie la transaction de manière unique et sera utilisé dans le cas de redirections et d'appels API ultérieurs.

TABLEAU 3.2 Requête et réponse SetCustomerBillingAgreement

Requête

[paramètresDeSécuritéRequis]&METHOD=SetCustomerBillingAgreement&BILLINGTYPE=Recu rringPayments&

RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html&

TABLEAU 3.3

Réponse

[champsDeRéponseRéussie]&TOKEN=RP-6WV965525F6410539

Spécifier un style de page de paiement personnalisé

Vous pouvez personnaliser le style des pages de paiement PayPal en définissant le paramètre PAGESTYLE dans SetCustomerBillingAgreement. Donnez à PAGEST YLE le nom de l'une des pages de paiement personnalisées que vous avez créées sur https://www.paypal.fr. Connectez-vous, cliquez sur Préférences puis sur Pages de paiement personnalisées.

L'exemple suivant définit PAGESTYLE comme DesignerFotos-Yellow dans la méthode

SetCustomerBillingAgreement

TABLEAU 3.4 Spécifier un style de page de paiement personnalisé

Requête

[paramètresDeSécuritéRequis]&METHOD=SetCustomerBillingAgreement&BILLINGTYPE=Recu rringPayments&

RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html&

PAGESTYLE=DesignerFotos-Yellow

TABLEAU 3.5

Réponse

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 41

[champsDeRéponseRéussie]&TOKEN=RP-6WV965525F6410539

Comment utiliser l'API Paiements récurrents

Personnaliser le logo et les couleurs

Modifiez les pages Web de PayPal de manière à ce qu'elles ressemblent à votre propre page Web en définissant les paramètres suivants dans SetCustomerBillingAgreement :

z HDRIMG : spécifie l'image que vous souhaitez voir apparaître en haut à gauche de la page de

paiement

TABLEAU 3.6 Personnaliser le logo et les couleurs individuellement

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=SetCustomerBillingAgreement&BILLINGTYPE=Recu rringPayments&

RETURNURL=https://www.masociété.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociété.com/traitement_commandes/infoslivraison.html&

HDRIMG=https://www.masociété.com/images/HeaderImage.gif& HDRBORDERCOLOR=3366FF&HDRBACKCOLOR=D3EFF5&PAYFLOWCOLOR=F8F5F5

TABLEAU 3.7

[champsDeRéponseRéussie]&TOKEN=RP-6WV965525F6410539

Rediriger le navigateur du client vers PayPal

Lorsque SetCustomerBillingAgreeement vous renvoie une réponse de réussite, ajouter la valeur de l'élément TOKEN fourni par la réponse SetCustomerBillingAgreeemen t sous forme de paire nom-valeur à l'URL suivante. Redirigez ensuite le navigateur de votre client vers cette URL :

https://www.paypal.com/cgi-bin /webscr?cmd=_custo mer-billing-agreement & token=value_from_SetExpressChe ckoutResponse

Pour rediriger le navigateur d'un client vers l'URL de PayPal, PayPal vous recommande d'utiliser la réponse HTTPS 302 «Objet déplacé» avec votre URL comme valeur de l'en-tête Location dans la réponse HTTPS. Si votre serveur utilise le protocole SSL, vous évitez que le navigateur ne reçoive des avertissements à propos d'un mélange d'images sécurisées et non sécurisées.

42 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Comment utiliser l'API Paiements récurrents

Obtenir les informations du payeur à l'aide de GetBillingAgreementCustomerDetails

Obtenir les informations du payeur à l'aide de

GetBillingAgreementCustomerDetails

La méthode GetBillingAgreementCustomerDetails renvoie les informations du client, y compris ses nom et adresse enregistrés par PayPal. Vous pouvez, si vous le désirez, appeler cette API dès que PayPal a redirigé le navigateur du client vers l'URL de renvoi que vous avez spécifié dans la requête SetCustomerBillingAgreement.

REMARQUE : appeler GetBillingAgreementCustomerDetails n'est pas obligatoire.

La requête GetBillingAgreementCustomerDetails contient un paramètre obligatoire, TOKEN, qui correspond à la valeur renvoyée dans la réponse SetCustomerBillingAgreement.

La réponse GetBillingAgreementCustomerDetails contient ce TOKEN ainsi que les informations du client.

TABLEAU 3.8 Obtenir les informations du payeur

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=GetBillingAgreementCustomerDetails& TOKEN=RP-6WV965525F6410539

TABLEAU 3.9

[champsDeRéponseRéussie]&TOKEN=RP-6WV965525F6410539&EMAIL=abcdef@anyemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=vérifié&FIRSTNAME=Pierre& LASTNAME=Dupont&COUNTRYCODE=US& SHIPTONAME=Pierre Dupont&SHIPTOSTREET=by 10 rue de la République& SHIPTOCITY=Paris&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US& SHIPTOZIP=75015&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmé

Effectuer la transaction à l'aide de

CreateRecurringPaymentsProfile

Dès que votre client a approuvé la transaction sur votre page de confirmation, appelez CreateRecurringPaymentsProfile afin de créer le profil et de clôturer la transaction.

IMPORTANT : la transaction de paiement récurrent n'est pas terminée tant que vous n'avez

pas appelé CreateRecurringPaymentsProfile.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 43

Comment utiliser l'API Paiements récurrents

Effectuer la transaction à l'aide de CreateRecurringPaymentsProfile

Vous devez toujours inclure les paramètres obligatoires dans la requête CreateRecurringPaymentsProfile.

TABLEAU 3.10 Champs de CreateRecurringPaymentsProfile

Nom Obligatoire ?

TOKEN

PROFILESTARTDATE Oui BILLINGPERIOD Oui

BILLINGFREQUENCY

AMT Oui TOTALBILLINGCYCLES Non SHIPPINGAMT Non TAXAMT Non MAXFAILEDPAYMENTS Non DESCRIPTION Non PROFILEREFERENCE Non

Oui

Dans le champ MaxFailedPayments, spécifiez le nombre de paiements rejetés autorisé. Vous pouvez vous servir librement des champs Description et ProfileReference.

En outre, si vous désirez ajouter une période d'essai au profil, vous devez inclure les champs suivants :

ABLEAU 3.11 Champs supplémentaires pour la période d'essai

Nom Obligatoire

TRIALBILLINGPERIOD Oui TRIALBILLINGFREQUENCY Oui TRIALAMT Oui TRIALTOTALBILLINGCYCLES Non TRIALSHIPPINGAMT Non TRIALTAXAMT Non

44 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Comment utiliser l'API Paiements récurrents

Effectuer la transaction à l'aide de CreateRecurringPaymentsProfile

Effectuer la transaction à l'aide de

CreateRecurringPaymentsProfile

TABLEAU 3.12 Requête et réponse CreateRecurringPaymentsProfile

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=CreateRecurringPaymentsProfile& TOKEN=RP-6WV965525F6410539&PROFILESTARTDATE=2007-10-12& TRIALBILLINGPERIOD=Month&TRIALBILLINGFREQUENCY=3&TRIALTOTALBILLINGCYCLES=2& TRIALAMT=5.99&BILLINGPERIOD=Month&BILLINGFREQUENCY=3&TOTALBILLINGCYCLES=6& AMT=12.99

[champsDeRéponseRéussie]&PROFILEID=4DK48DKD9D030

Affichage et annulation des préférences relatives aux paiements récurrents L'acheteur et le marchand peuvent tout les deux afficher ou annuler les préférences des

paiements récurrents depuis le site PayPal. Il n'existe actuellement aucun accès API permettant aux marchands de modifier ou d'annuler

des préférences. Affichage des préférences relatives aux paiements récurrents.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 45

Comment utiliser l'API Paiements récurrents

Récapitulatif des Préférences de paiements récurrents

Pour afficher les préférences relatives aux paiements récurrents, connectez-vous à votre compte, puis cliquez sur le lien Paiements récurrents dans la page Préférences.

Récapitulatif des Préférences de paiements récurrents

Cliquez sur le lien Afficher les détails d'une page de préférences pour afficher un récapitulatif de ces préférences, ainsi qu'illustré en Figure 3.1.

46 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Comment utiliser l'API Paiements récurrents

Récapitulatif des Préférences de paiements récurrents

FIGURE 3.1 Détails des paiements récurrents

Annulation des préférences relatives aux paiements récurrents L'acheteur et le vendeur sont tout deux en mesure d'annuler les préférences relatives aux

paiements récurrents. Il suffit pour cela de cliquer sur Annuler dans l'écran affichant les détails des paiements récurrents. La fenêtre en Figure 3.2 s'affiche.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 47

Comment utiliser l'API Paiements récurrents

Récapitulatif des Préférences de paiements récurrents

FIGURE 3.2 Annuler les Préférences de paiements récurrents

Si le client clique sur Oui, les préférences sont annulées.

48 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Fonctions de gestion

Cette section présente des exemples des fonctions suivantes :

z « Collecter, Autoriser, Annuler et Demander une nouvelle autorisation » page 49 z « Effectuer un remboursement à l'aide de RefundTransaction » page 51 z « Rechercher une transaction à l'aide de TransactionSearch » page 52 z « Visualiser les détails d'une seule transaction à l'aide de GetTransactionDetails » page 53

Collecter, Autoriser, Annuler et Demander une nouvelle

autorisation

Quatre API se rapportent à la fonction Autorisation et collecte :

z DoCapture z DoAuthorization z DoVoid z DoReauthorization

IMPORTANT : pour les utiliser, vous devez connaitre la valeur TRANSAC TIONID de la

transaction initiale. Utilisez la valeur initiale de TRANSACTIONID comme valeur d'AUTHORIZATIONID avec DoCapture, DoAuthorizati on, DoVoid et DoReauthorization.

Effectuer une collecte unique dans une commande à l'aide de

DoCapture

Pour effectuer une collecte unique, vous devez définir le numéro d'identification de l'autorisation et le montant sur DoCapture.

IMPORTANT : effectuer la collecte une seule fois est la valeur par défaut. Par souci de

précision, vous pouvez également définir COMPLETETYPE=Complete.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 49

Fonctions de gestion

Effectuer plusieurs collectes partielles dans une commande à l'aide de DoCapture

COMPLETETYPE=Complete clôture toutes les autorisations en cours de la commande. Vous ne pouvez plus effectuer de collecte.

FIGURE 4.1 Collecter l'intégralité du montant d'une autorisation

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoCapture&AUTHORIZATIONID=01987219673867 &AMT=99.12&COMPLETETYPE=Complete

[champsDeRéponseRéussie]&AUTHORIZATIONID=01987219673867 &TRANSACTIONID=7JZ9679864YA2699519&PARENTTRANSACTIONID=01987219673867 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=express-checkout &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=99.12 &CURRENCYCODE=EUR&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Effectuer plusieurs collectes partielles dans une commande à

l'aide de DoCapture

Vous pouvez collecter une partie du montant d'une autorisation en définissant COMPLETETYPE=NotComplete

Lors de la collecte finale, définissez COMPLETETYPE=Complete ou omettez de spécifier COMPLETETYPE.

Cet exemple illustre trois collectes :

z Les deux premières collectes sont partielles. La valeur de COMPLETETYPE est

NotComplete

z Le dernière collecte est effectuée pour l'intégralité du montant restant. La valeur de

COMPLETETYPE est Complete.

FIGURE 4.2 Collecter une partie du montant d'une autorisation

Première requête de collecte partielle

Réponse

50 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

[paramètresDeSécuritéRequis]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=112.00&COMPLETETYPE=NotComplete

[champsDeRéponseRéussie]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=4Y117666R06578920&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:23:15Z&AMT=112.00 &CURRENCYCODE=EUR&FEEAMT=3.55&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Fonctions de gestion

Insérer un numéro de facture et une remarque lors de la collecte à l'aide de DoCapture

Deuxième requête de collecte partielle

Réponse

Requête de collecte finale

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=NotComplete

[champsDeRéponseRéussie]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=7JY48864YA2699519&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=103.12 &CURRENCYCODE=EUR&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

[paramètresDeSécuritéRequis]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=Complete

[champsDeRéponseRéussie]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=7JZ89864YA2699519&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=90.80 &CURRENCYCODE=EUR&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Insérer un numéro de facture et une remarque lors de la collecte

à l'aide de DoCapture

Que la collecte soit effectuée pour un montant intégral ou partiel, vous avez la possibilité d'insérer une remarque sur la collecte ainsi que votre propre numéro de facture ou tout autre numéro d'identification.

FIGURE 4.3 Inclure un numéro de facture et une remarque lors de la collecte

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &COMPLETETYPE=Complete&AMT=304.92&INVNUM=H091234&NOTE=UPS+trk#+b86283978

[champsDeRéponseRéussie]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=7JZ89864YA2694419&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=304.92 &CURRENCYCODE=EUR&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Effectuer un remboursement à l'aide de RefundTransaction

Grâce à RefundTransaction, vous pouvez ef fectuer un remboursement du mont ant intégral ou d'un montant partiel d'une transaction. Spécifiez le numéro de la transaction initiale et le type de remboursement : Intégral ou Partiel.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 51

Fonctions de gestion

Rechercher une transaction à l'aide de TransactionSearch

Remboursement intégral

IMPORTANT : si vous désirez rembourser le montant dans son intégralité, n'assignez pas

de valeur au champ AMT.

FIGURE 4.4 Rembourser le montant intégral de la transaction

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=RefundTransaction& TRANSACTIONID=019454569673867&REFUNDTYPE=Full

[champsDeRéponseRéussie]&REFUNDTRANSACTIONID=4RP55200GJ177180N &FEEREFUNDAMT=4.01&GROSSREFUNDAMT=127.87&NETREFUNDAMT=123.86

Remboursements partiels

Pour effectuer un remboursement partiel, assignez à REFUNDTYPE la valeur Partiel et définissez AMT.

FIGURE 4.5 Rembourser une partie du montant

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=RefundTransaction &TRANSACTIONID=9CX07910UV614511L&REFUNDTYPE=Partial&AMT=12.95

[champsDeRéponseRéussie]&REFUNDTRANSACTIONID=1H0011898K637700R &FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

Insérer une remarque lors du remboursement

Que le remboursement soit intégral ou partiel, vous avez également la possibilité d'insérer une remarque à son sujet.

FIGURE 4.6 Insérer une remarque lors du remb ourse me nt

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=RefundTransaction& TRANSACTIONID=019454569673867&REFUNDTYPE=Partial&AMT=12.95&

NOTE=Customer+changed+mind.

[champsDeRéponseRéussie]&REFUNDTRANSACTIONID=1H0011898K637700R &FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

Rechercher une transaction à l'aide de TransactionSearch

Pour trouver toutes les transactions effectuées à une date particulière, utilisez TransactionSearch et saisissez la date de votre choix dans le champ STARTDATE. La date doit obligatoirement être au format UTC/GMT.

52 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Visualiser les détails d'une seule transaction à l'aide de GetTransactionDetails

FIGURE 4.7 Rechercher des transactions par STARTDATE

Fonctions de gestion

Requête

Réponse

[paramètresDeSécuritéRequis]&METHOD=TransactionSearch &STARTDATE=2006-08-15T17:00:00Z

[champsDeRéponseRéussie]&L_TIMESTAMP0=2006-08-18T05:58:41Z& L_TIMEZONE0=GMT&L_TYPE0=Authorization&L_NAME0=Pierre+Doe& L_TRANSACTIONID0=3XK029742B016373C&L_STATUS0=Pending&L_AMT0=1.00& L_TIMESTAMP1=2006-08-18T05:56:20Z&L_TIMEZONE1=GMT&L_TYPE1=Payment& L_NAME1=Pierre+Doe&L_TRANSACTIONID1=4BV19600WF261673U&L_STATUS1=Completed &L_AMT1=1.00&L_FEEAMT1=-0.33&L_NETAMT1=0.67& L_TIMESTAMP2=2006-08-18T05:53:22Z&L_TIMEZONE2=GMT&L_TYPE2=Payment &L_NAME2=Pierre+Doe&L_TRANSACTIONID2=6XB50622KC566325C&L_STATUS2=Completed &L_AMT2=1.00&L_FEEAMT2=-0.33&L_NETAMT2=0.67& L_TIMESTAMP3=2006-08-18T05:38:04Z&L_TIMEZONE3=GMT &L_TYPE3=Payment&L_NAME3=Pierre+Doe&L_TRANSACTIONID3=80774637LP956560E& L_STATUS3=Completed&L_AMT3=1.00&L_FEEAMT3-0.33&L_NETAMT3=0.67& L_TIMESTAMP4=2006-08-17T03:02:44Z&L_TIMEZONE4=GMT&L_TYPE4=Payment& L_NAME4=Pettibone+Smythe-Jones&L_TRANSACTIONID4=8G40321568512733L& L_STATUS4=Completed&L_AMT4=104.00&L_FEEAMT4=-3.32&L_NETAMT4=100.68

TransactionSearch renvoie un tableau multi-valeurs de toutes les transactions correspondant aux critères de recherche. Chaque transaction débute par sa date : L_TIMESTAMP

n, où n

commence par 0 et augmente d'une unité pour chaque transaction.

Visualiser les détails d'une seule transaction à l'aide de

GetTransactionDetails

Pour visualiser tous les détails d'une seule transaction, utiliser GetTransactionDetails.

FIGURE 4.8 Visualiser les détails d'une transaction

Requête

Réponse

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 53

[paramètresDeSécuritéRequis]&METHOD=GetTransactionDetails &TRANSACTIONID=3B288546P5019992D

[champsDeRéponseRéussie]&RECEIVERBUSINESS=Jims+Hardware &RECEIVEREMAIL=jim@hardwareplace.com&RECEIVERID=WNSJNN89XVWFA &PAYERID=B3KS3VFYNG9SN&PAYERSTATUS=invérifié&FIRSTNAME=James& LASTNAME=Biguy&COUNTRYCODE=US&SHIPTOSTATE=&ADDRESSID=PayPal&ADDRESSSTATUS=None &TRANSACTIONID=3B288546P5019992D&RECEIPTID=3596-6202-14612615 &TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant& ORDERTIME=2006-08-15T17:00:00Z&AMT=127.87&CURRENCYCODE=EUR&FEEAMT=4.01 &TAXAMT=0.00&PENDINGREASON=None&REASONCODE=None&SALESTAX=0.00&L_QTY0=1

Fonctions de gestion

Visualiser les détails d'une seule transaction à l'aide de GetTransactionDetails

54 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes

et des champs de l'API NVP

Caractéristiques générales des requêtes et des paramètres

Paramètres

La chaîne des paramètres d'une requête obéit à la syntaxe des composants d'une demande définie dans l' paramètres peuvent être soit en lettres majuscules, soit en lettres minuscules. Par souci de clarté, nous utiliserons ici des majuscules. L'encodage dans l'URL de toutes les valeurs doit être assuré.

Champs multi-valeurs

Les champs acceptant des valeurs multiples ont des noms tels que :

L_FIELDNAMEn

Uniform Resource Identifier (URI) : syntaxe générique. Les noms et les valeurs des

où L_ est littéral, FIELDNAME est le nom du paramètre et n est le numéro d'index, en commençant avec 0 et incrémenté d'une unité pour chaque valeur du champ. Les numéros d'index doivent être séquentiels.

Par exemple, dans le cas d'une commande d'objets multiples, il vous est possible d'ajouter un coût d'objet pour chaque objet à l'aide du paramètre L_

L_AMT0=4.95&L_AMT1=6.72&L_AMT2=7.95

Devises acceptées par PayPal

Les devises suivantes sont acceptées par PayPal.

TABLEAU A.1 Devises acceptées par PayPal et codes de devises pour les

transactions

Code ISO4217 Devise

AUD Dollar australien CAD Dollar canadien CHF Franc suisse CZK Couronne tchèque

AMTn :

DKK Co uro nne danoise

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 55

Liste de référence des méthodes et des champs de l'API NVP

Caractéristiques générales des requêtes et des paramètres

TABLEAU A.1 Devises acceptées par PayPal et codes de devises pour les

transactions (suite)

Code ISO4217 Devise

EUR Euro GBP Liv re sterling HKD Dollar de Hong-Kong HUF Forint hongrois JPY Yen japonais NOK Couronne norvégienne NZD Dollar néo-zélandais PLN Zloty polonais SEK Couronne suédoise SGD Dollar de Singapour USD Dollar américain

ABLEAU A.2 Adresse de livraison (facultatif)

Paramètre Description Obligatoire ?

SHIPTONAME Nom de la personne associée à cette adresse.

Nombre de caractères limite : 32 caractères d'un octet.

SHIPTOSTREET Première adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOCITY Nom de la ville.

Nombre de caractères limite : 40 caractères d'un octet.

SHIPTOSTATE Etat ou province.

Nombre de caractères limite : 40 caractères d'un octet. Pour une abréviations des états ou provinces, reportez-vous à l’

Oui

Non

«Abréviations des états ou provinces» page 57.

Requis pour les adresses américaines (USA) seulement.

SHIPTOZIP

Code postal américain ou code postal spécifique aux autres pays. Nombre de caractères limite : 20 caractères d'un octet.

Oui

56 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Caractéristiques générales des requêtes et des paramètres

ABLEAU A.2 Adresse de livraison (facultatif) (suite)

Paramètre Description Obligatoire ?

SHIPTOCOUNTRYCODE Code pays.

Nombre de caractères limite : 2 caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

«Codes pays»

SHIPTOSTREET2 Seconde adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOPHONENUM Numéro de téléphone.

Nombre de caractères limite : 20 caractères d'un octet.

Abréviations des états ou provinces

Le tableau ci-dessous répertorie abréviations pour les provinces canadiennes et les états américains. Entrez ces valeurs dans les paramètres STATE ou SHIPTOSTATE.

ABLEAU A.3 Abréviations pour les provinces canadiennes e t les ét ats américa ins

Province canadienne ou état américain Abréviation

Alberta AB Colombie-Britannique BC

Oui

Annexe F,

Non

Manitoba MB Nouveau Brunswick NB Terre-Neuve et Labrador NF Territoires du Nord-Ouest NT Nouvelle-Ecosse NS Nunavut NU Ontario ON Ile du Prince-Edouard PE Québec QC Saskatchewan SK Yukon YK Alabama AL Alaska AK

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 57

Liste de référence des méthodes et des champs de l'API NVP

Caractéristiques générales des requêtes et des paramètres

ABLEAU A.3 Abréviations pour les provinces canadiennes e t les ét ats américa ins

(suite)

Province canadienne ou état américain Abréviation

Samoa Américaines AS Arizona AZ Arkansas AR Californie CA Colorado CO Connecticut CT Delaware DE District de Columbia DC Etats fédérés de Micronésie FM Floride FL Géorgie GA Guam GU Hawaii HI Idaho ID Illinois IL Indiana IN Iowa IA Kansas KS Kentucky KY Louisiane LA Maine ME Iles Marshall MH Maryland MD Massachusetts MA Michigan MI Minnesota MN Mississippi MS

58 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Caractéristiques générales des requêtes et des paramètres

ABLEAU A.3 Abréviations pour les provinces canadiennes e t les ét ats américa ins

(suite)

Province canadienne ou état américain Abréviation

Missouri MO Montana MT Nebraska NE Nevada NV New Hampshire NH New Jersey NJ Nouveau Mexique NM New York NY Caroline du Nord NC Dakota du Nord ND Iles Mariannes du Nord MP Ohio OH Oklahoma OK Oregon OR Palaos PW Pennsylvanie PA Porto Rico PR Rhode Island RI Caroline du Sud SC Dakota du Sud SD Tennessee TN Texas TX Utah UT Vermont VT Iles Vierges VI Virginie VA Washington WA

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 59

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.3 Abréviations pour les provinces canadiennes e t les ét ats américa ins

(suite)

Province canadienne ou état américain Abréviation

Virginie-Occidentale WV Wisconsin WI Wyoming WY Forces armées Amériques AA Forces armées Europe AE Forces armées Pacifique AP

Paiement express PayPal

Requête SetExpressCheckout

ABLEAU A.4 Paramètres de la requête SetExpressCheckout

Paramètre Description Obligatoire

METHOD Nom de l'API : SetE xpressCheckout Oui RETURNURL URL vers laquelle le navigateur du client est renvoyé après avoir choisi de

payer avec PayPal.

REMARQUE : PayPal recommande que la valeur corresponde à la

page de vérification finale sur laquelle le client confirme la commande et le paiement ou l'autorisation de facturation.

Nombre de caractères limite : pas de limite.

CANCELURL URL vers laquelle le client est renvoyé s'il n'approuve pas l'utilisation de

PayPal pour vous payer.

REMARQUE : PayPal recommande que la valeur corresponde à la

page initiale sur laquelle le client a choisi de payer avec PayPal ou d'établir une autorisation de facturation.

Nombre de caractères limite : pas de limite.

Oui

60 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.4 Paramètres de la requête SetExpressCheckout (s uite)

Paramètre Description Obligatoire

AMT Coût total de la commande pour le client. Si vous connaissez les frais

d'expédition, de livraison et de TVA, incluez-les dans cette valeur; dans le cas contraire, cette valeur doit correspondre au sous-total actuel de la commande.

REMARQUE : limites : ne doit dé passer $10 000 USD dans aucune

devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif doit être un point (.).

CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

«Devises acceptées par PayPal» page 55. Par défaut : USD.

MAXAMT Montant total maximum prévu de la commande complète, y compris frais

d'expédition, de livraison et de TVA.

REMARQUE : limites : ne doit dé passer $10 000 USD dans aucune

devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif doit être un point (.).

PAYMENTACTION Mode d'obtention du paiement :

z A uthorization indique que ce paiement est une autorisation de base

qui sera traitée par Autorisation et collecte.

z O rder indique que ce paiement est une autorisation de commande qui

sera traitée par la fonction Autorisation et collectede PayPal.

z S ale indique qu'il s'agit d'une vente finale pour laquelle vous

demandez un paiement.

Oui

Non

REMARQUE : vous ne pouvez pas définir cette valeur sur Sale dans

la requête SetExpressCheckout, puis la définir sur Authorization dans la requête DoExpressCheckoutPayment de l'API finale.

Nombre de caractères limite : jusqu'à 13 caractères alphabétiques d'un octet.

Valeurs autorisées:

z A uthorization z O rder z S ale

Par défaut : La transaction résultant de la requête

DoExpressCheckoutPayment est une vente finale..

EMAIL Adresse email de l'acheteur entrée pendant le paiement. PayPal utilise cette

Non valeur pour pré-remplir la partie réservée à l'inscription pour l'adhésion à PayPal de la page de connexion PayPal.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

DESC Description des objets achetés par le client.

Non Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 61

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.4 Paramètres de la requête SetExpressCheckout (s uite)

Paramètre Description Obligatoire

CUSTOM Champ à structure non imposée que vous utilisez librement, par exemple

un numéro de suivi ou toute autre valeur que vous souhaitez que PayPal renvoie dans la réponse GetExpressCheckoutDetails et dans la réponse DoExpressCheckoutPayment.

Nombre de caractères limite : 256 caractères alphanumériques d'un octet.

INVNUM Votre numéro de factu re ou de suiv i personnel. PayPal vous renvoie cette

valeur dans la réponse DoExpressCheckoutPayment. Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

REQCONFIRMSHIPPING La valeur 1 indique que vous demandez que l'adresse de livraison du client

enregistrée chez PayPal soit une adresse confirmée.

REMARQUE : si vous définissez ce champ, le paramètre que vous avez

indiqué dans vos Préférences de compte marchand est remplacé.

Nombre de caractères limite : un caractère numérique d'un octet. Valeurs autorisées : 0, 1 Par défaut : 0

NOSHIPPING La valeur 1 indique qu'au cu n champ d'adresse de livraison ne doit

apparaître sur les pages de PayPal. Nombre de caractères limite : quatre caractères numériques d'un octet. Valeurs autorisées : 0, 1 Par défaut : 0

Non

ADDROVERRIDE La vale ur 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.

REMARQUE : le fait d'afficher l'adresse postale enregistrée chez

PayPal ne permet pas au client de modifier cette adresse.

Valeurs autorisées : 0, 1 Par défaut : 0

TOKEN Jeton horodaté par lequel vous indiquez à PayPal que vous traitez ce

paiement avec la fonction Paiement express PayPal.

REMARQUE : le jeton expire au bout de trois heures.

Si vous avez défini le jeton dans la requête SetExpress Checkout, sa valeur dans la réponse est identique à celle de la requête.

Nombre de caractères limite : 20 caractères d'un octet. Valeurs autorisées : Consultez la description de la variable TOKEN dans

Tableau A.6, «Champs de la réponse SetExpressCheckout».

Non

62 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.4 Paramètres de la requête SetExpressCheckout (s uite)

Paramètre Description Obligatoire

LOCALECODE Paramètre régio nal des pages af fic hées par PayPal pend ant la proc édure de

Paiement express PayPal. Nombre de caractères limite : N'importe quel code pays de deux caractères. Les codes pays de deux caractères suivants sont pris en charge par PayPal :

z AU z DE z FR z IT z GB z ES z US

Toute autre valeur sera remplacée par défaut par US.

REMARQUE : pour consulter la liste des codes pays, reportez-vous à

l’

Annexe F, «Codes pays».

PAGESTYLE Détermine le style personnalisé des pages de paiement associées à ce

bouton/lien. Cette valeur correspond à la variable HTML page_style qui permet de personnaliser ces pages. La valeur est identique au nom du style choisi lors de l'ajout ou de la modification du style de page du sous-onglet Préférences de l'onglet Mon compte sur le site PayPal.

Nombre de caractères limite : 30 caractères alphabétiques d'un octet.

HDRIMG URL de l'image que vous souhaitez voir apparaître dans la partie

supérieure gauche de la page de paiement. La taille maximale de l'image est de 750 pixels en largeur et de 90 pixels en hauteur. PayPal vous recommande de fournir une image stockée sur un serveur sécurisé (https).

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

Non

HDRBORDERCOLOR Définit la couleur de bordure de l'en-tête de la page de paiement. La

Non bordure est un périmètre de 2 pixels autour de l'espace d'en-tête, qui dispose d'une taille de 750 pixels de large sur 90 pixels de haut.

Nombre de caractères limite : code couleur hexadécimal HTML de six caractères en ASCII.

HDRBACKCOLOR Définit la couleur d'arrière-plan de l'en-tête de la page de paiement.

Non Nombre de caractères limite : code couleur hexadécimal HTML de six

caractères en ASCII.

PAYFLOWCOLOR Définit la couleur d'arrière-plan de la page de paiement.

Non Nombre de caractères limite : code couleur hexadécimal HTML de six

caractères en ASCII.

L_PROMOCODE0 Un code de promotion tel que le Code financier promo tionnel des services

Non marchands. Vous pouvez combiner des promotions en utilisant des paires nom-valeur telles que L_PROMOCODE1, L_PROMOCODE2, etc.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 63

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.4 Paramètres de la requête SetExpressCheckout (s uite)

Paramètre Description Obligatoire

Adresse de livraison Adresse de livraison facultative. Les paramètres de l'adresse de livraison

facultative sont décrits dans

(facultatif)»

IMPORTANT : l'adresse de livraison est facultative mais si vous

l'incluez, certains champs doivent être saisis.

ABLEAU A.5 Adresse de livraison (facultatif)

Paramètre Description Obligatoire

SHIPTONAME Nom de la personne associée à cette adresse de livraison.

Nombre de caractères limite : 32 caractères d'un octet.

SHIPTOSTREET Première adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOCITY Nom de la ville.

Nombre de caractères limite : 40 caractères d'un octet.

SHIPTOSTATE Etat ou province.

Nombre de caractères limite : 40 caractères d'un octet. Requis pour les adresses américaines (USA) seulement.

SHIPTOCOUNTRYCODE Code Pays.

Nombre de caractères : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

«Codes pays»

Tableau A.5, «Adresse de livraison

Annexe F,

Non

Oui

Non

Oui

SHIPTOZIP Code postal américain ou code postal spécifique aux autres pays.

Nombre de caractères limite : 20 caractères d'un octet

SHIPTOSTREET2 Seconde adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

PHONENUM Numéro de téléphone.

Nombre de caractères limite : 20 caractères d'un octet.

Oui

Non

64 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

Réponse SetExpressCheckout

TABLEAU A.6 Champs de la réponse SetExpressCheckout

Paramètre Description

TOKEN Jeton horodaté par lequel vous indiquez à PayPal que vous traitez ce paiement avec la

fonction Paiement express PayPal.

REMARQUE : le jeton expire au bout de trois heures.

Si vous avez défini le jeton dans la requête SetExpressCheckout, sa valeur dans la réponse est identique à celle de la requête.

Nombre de caractères limite : 20 caractères d'un octet.

Rediriger le navigateur du client vers la page de connexion PayPal

Lorsque vous avez reçu une réponse de SetExpressCheckout, ajoutez la valeur de l'élément TOKEN de SetExpressCheckout sous forme de paire nom-valeur à l'URL suivante et redirigez-y le navigateur de votre client :

https://www.paypal.com/cgi-bin /webscr?cmd=_expre ss-checkout& token=value_from_SetExpressChe ckoutResponse

Pour rediriger le navigateur d'un client vers la page de connexion PayPal, PayPal vous recommande d'utiliser la réponse HTTPS 302 «Objet déplacé» avec l'URL ci-dessus comme valeur de l'en-tête Location dans la réponse HTTPS. Si votre serveur utilise le protocole SSL, vous évitez que le navigateur ne reçoive des avertissements à propos d'un mélange d'images sécurisées et non sécurisées.

Requête GetExpressCheckoutDetails

ABLEAU A.7 Paramètres de GetExpressCheckoutDetails

Paramètre Description Obligatoire ?

METHOD Nom de l'API : GetExpressCheckoutDetails Oui TOKEN Jeton horodaté dont la valeur a été renvoyée par la réponse

SetExpressCheckout.

Nombre de caractères limite : 20 caractères d'un octet. Valeurs autorisées : Un jeton non périmé

Oui

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 65

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

Réponse GetExpressCheckoutDetails

TABLEAU A.8 Champs de la réponse GetExpressCheckoutDetails

Champ Description

TOKEN Valeur du jeton horodaté qui a été renvoyée par la réponse

SetExpressCheckout et transmise dans la requête GetExpressCheckoutDetails.

Nombre de caractères limite : 20 caractères d'un octet. Valeurs possibles : Consultez la description de JETON dans

A.6, «Champs de la réponse SetExpressChe ckout»

EMAIL Adresse email du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

PAYERID Numéro de compte unique du client PayPal.

Nombre de caractères limite:13 caractères alphanumériques d'un octet.

PAYERSTATUS Etat du payeur.

Nombre de caractères limite : 10 caractères alphabétiques d'un octet. Valeurs possibles : verified, unverified

Tableau

SALUTATION Formule d'appel du payeur.

Nombre de caractères limite : 20 caractères d'un octet.

FIRSTNAME Prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

MIDDLENAME Deuxième prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

LASTNAME Nom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

SUFFIX Suffixe du payeur.

Nombre de caractères limite : 12 caractères d'un octet.

COUNTRYCODE Pays de résidence du payeur sous forme de code pays ISO 3166 à deux

caractères. Nombre de caractères limite : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

«Codes pays»

BUSINESS Raison sociale du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

SHIPTONAME Nom de la personne associée à cette adresse.

Nombre de caractères limite : 32 caractères d'un octet.

Annexe F,

66 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.8 Champs de la réponse GetExpressCheckoutDetails (sui te)

Champ Description

SHIPTOSTREET Première adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOSTREET2 Seconde adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOCITY Nom de la ville.

Nombre de caractères limite : 40 caractères d'un octet.

SHIPTOSTATE Etat ou province.

Nombre de caractères limite : 40 caractères d'un octet.

SHIPTOCOUNTRYCODE Code pays.

Nombre de caractères : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

«Codes pays»

SHIPTOZIP Code postal américain ou code postal spécifique aux autres pays.

Nombre de caractères limite : 20 caractères d'un octet.

Annexe F,

ADDRESSSTATUS Etat de l'adresse postale enregistrée chez PayPal CUSTOM Champ à structure non imposée que vous utilisez librement et défini par

vos soins dans l'élément Custom de la requête SetExpressCheckout. Nombre de caractères limite : 256 caractères alphanumériques d'un

octet.

INVNUM Votre numéro de facture ou de suivi personnel, défini par vos soins dans

l'élément du même nom dans la requête SetExpressCheckout. Nombre de caractères limite : 127 caractères alphanumériques d'un

octet.

PHONENUM Numéro de téléphone à contacter du payeur.

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

Nombre de caractères limite : le masque du champ est XXX -XXXXXXX (pour les numéros aux Etats-Unis) ou +XXX XXXXXXXX (pour les autres numéros)

Requête DoExpressCheckoutPayment

Requête pour obtenir le paiement via la fonction Paiement express PayPal de PayPal.

IMPORTANT : PayPal exige qu'un vendeur utilisant Paiement express PayPal affiche pour

le client un montant identique à celui qu'il envoie à PayPal dans le paramètre AMT avec la requête API DoExpressCheckoutPayment.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 67

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

TABLEAU A.9 Paramètre DoExpressCheckoutPayment

Paramètre Description Obligatoire ?

METHOD Nom de l'API : DoExpressCheckoutPayment Oui TOKEN Valeur du jeton horodat é qui a été renvoyée par la répo nse

SetExpressCheckout et transmise dans la requête GetExpressCheckoutDetails.

Nombre de caractères limite : 20 caractères d'un octet.

PAYMENTACTION Mode d'obtention du paiement :

z Au thorization indique que ce paiement est une autorisation de base

qui sera traitée par Autorisation et collecte.

z Or der indique que ce paiement est une autorisation de commande qui

sera traitée par la fonction Autorisation et collectede PayPal.

z Sa le indique qu'il s'agit d'une vente finale pour laquelle vous

demandez un paiement.

REMARQUE : vous ne pouvez pas définir cette valeur sur Sale dans

la requête SetExpressCheckout, puis la définir sur Authorization dans la requête DoExpressCheckoutPayment de l'API finale.

Nombre de caractères limite : jusqu'à 13 caractères alphabétiques d'un octet.

Valeurs autorisées :

z Au thorization z Or der z Sa le

Par défaut : la transaction résultant de requête DoExpressCheckoutPayment une vente finale..

Oui

PAYERID Numéro de compte client PayPal unique renvoyé par la réponse

Oui

GetExpressCheckoutDetails. Nombre de caractères limite : 13 caractères alphanumériques d'un octet.

AMT Total de la commande, incl uant les frais d'expédition et de livraison, de

Oui

dossier et le montant de la TVA.

REMARQUE : Limites : ne doit dépasser $10 000 USD dans aucune

devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif doit être un point (.).

DESC Description des objets achetés par le client.

Non

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

CUSTOM Champ à structure non imposée que vous utilisez librement.

Non

Nombre de caractères limite : 256 caractères alphanumériques d'un octet.

68 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.9 Paramètre DoExpressCheckoutPayment (suite)

Paramètre Description Obligatoire ?

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

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

BUTTONSOURCE Code d'identification permettant aux applications tierces d'identifier les

transactions. Nombre de caractères limite : 32 caractères alphanumériques d'un octet.

NOTIFYURL Votre URL pour la réception de la Notification instantanée de paiement

(NIP) concernant cette transaction.

REMARQUE : si vous ne spécifiez pas cette valeur dans la requête,

c'est l'URL de notification de vos Préférences du marchand qui est utilisée, s'il en existe une.

Nombre de caractères limite : 2 048 caractères alphanumériques d'un octet.

ITEMAMT Somme des frais de tous les objets de cette commande.

Limites : ne doit dépasser $10 000 USD dans aucune devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultati f doit être un point (.).

REMARQUE : ITEMAMT est nécessaire si vous spécifiez une valeur

pour L_AMT

SHIPPINGAMT Total des frais d'expédition et de livraison de cette commande.

REMARQUE : nombre de caractères limite : ne doit dépasser

$10 000 USD dans aucune devise. Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

Non

HANDLINGAMT Total des frais de dossier de cette commande.

REMARQUE : nombre de caractères limite : ne doit dépasser

Non

TAXAMT Somme des frais de TVA de tous les objets de cette commande.

REMARQUE : nombre de caractères limite : ne doit dépasser

Non

REMARQUE : TAXAMT est nécessaire si vous spécifiez une valeur pour

L_TAXAMT

CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

Devises de transaction acceptées par PayPal

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 69

Non

. Par défaut : USD

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.9 Paramètre DoExpressCheckoutPayment (suite)

Paramètre Description Obligatoire ?

L_NAMEn Nom de l'objet

Nombre de caractères limite : 127 caractères d'un octet. Il est conseillé d’organiser ces paramètres de manière

séquentielle en commençant par 0, par exemple, L_NAME0,

L_NAME1, et ainsi de suite.

L_NUMBERn Numéro de l'objet.

Nombre de caractères limite : 127 caractères d'un octet.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_NUMBER0,

L_NUMBER1, et ainsi de suite.

L_QTYn Quantité d'obj ets.

Nombre de caractères limite : n'importe quel chiffre entier positif.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_QTY0,

L_QTY1, et ainsi de suite.

L_TAXAMTn TVA concernant l'objet.

Nombre de caractères limite : ne doit dépasser $10 000 USD dans aucune devise. Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_TAXAMT0, L_TAXAMT1, et ainsi de suite.

Non

L_AMTn Coût de l'objet.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_AMT0,

L_AMT1, et ainsi de suite.

L_PROMOCODE0 Un code de promotion tel que le Code financier promotionnel des services

marchands. Vous pouvez combiner des promotions en utilisant des paires nom-valeur telles que L_PROMOCODE1, L_PROMOCODE2, etc.

Adresse de livraison Adresse de livraison facultative. Les paramètres de l'adresse de livraison

facultative sont décrits dans

livraison»

IMPORTANT : l'adresse de livraison est facultative mais si vous

l'incluez, certains champs doivent être saisis.

Tableau A.10, «Facultatif Adresse de

Non

70 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

TABLEAU A.10 Facultatif Adresse de livraison

Paramètre Description Obligatoire ?

SHIPTONAME Nom de la personne associée à cette adresse.

Nombre de caractères limite : 32 caractères d'un octet.

SHIPTOSTREET Première adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOCITY Nom de la vi l le.

Nombre de caractères limite : 40 caractères d'un octet.

SHIPTOSTATE Etat ou province.

Nombre de caractères limite : 40 caractères d'un octet. Requis pour les adresses américaines (USA) seulement.

SHIPTOCOUNTRYCODE Code pays.

Nombre de caractères : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

«Codes pays»

SHIPTOZIP Code postal américain ou code postal spécifique aux autres pays.

Nombre de caractères limite : 20 caractères d'un octet.

SHIPTOSTREET2 Seconde adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

SHIPTOPHONENUM Numéro de téléphone.

Nombre de caractères limite : 20 caractères d'un octet.

Annexe F,

Oui

Non

Oui

Non

Réponse DoExpressCheckoutPayment

ABLEAU A.11 Champs de la réponse Paiement DoExpressCheckout

Champ Description

TOKEN Valeur du jeton horodat é qui a été renvoyée par la répo nse

SetExpressCheckout et transmise dans la requête GetExpressCheckoutDetails.

Nombre de caractères limite : 20 caractères d'un octet. Valeurs autorisées : Consultez la description de JETON dans

«Champs de la réponse SetExpressCheckout»

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 71

Tab leau A.6,

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.11 Champs de la réponse Paiement DoExpressCheckout (suite)

Champ Description

TRANSACTIONID Numéro de transaction unique du paiement.

REMARQUE : si l'élément PaymentAction de la requête est défini sur

Authorization ou sur Order, cette valeur correspond à votre

AuthorizationID à utiliser avec les API Autorisation et collecte.

Nombre de caractères limite : 19 caractères d'un octet. Valeurs possibles : Spécifique à la transaction

TRANSACTIONTYPE Type de transaction

Nombre de caractères limite : 15 caractères d'un octet. Valeurs possibles :

z ca rt z ex press-checkout

PAYMENTTYPE Indique si le paiement est immédiat ou différé.

Nombre de caractères limite : sept caractères d'un octet Valeurs possibles :

z none z echeck z instant

ORDERTIME Horodatage du paiement

Valeurs possibles : Spécifique à la transaction

AMT Montant final facturé, incluant les frais d'expédition, de livraison et de TVA

de vos Préférences du marchand. Nombre de caractères limite : ne dépasse $1 0 000 USD dans aucune devise.

Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

Valeurs possibles : Spécifique à la transaction

CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

Devises de transaction acceptées par PayPal

. Par défaut : USD.

FEEAMT Montant de la commission de PayPal facturée pour la transaction

Nombre de caractères limite : ne dépasse $1 0 000 USD dans aucune devise. Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

Valeurs possibles : Spécifique à la transaction

SETTLEAMT Montant déposé sur votre compte PayPal après conversion de devise.

Valeurs possibles : Spécifique à la transaction

72 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiement express PayPal

ABLEAU A.11 Champs de la réponse Paiement DoExpressCheckout (suite)

Champ Description

TAXAMT TVA facturée pour la transaction.

Valeurs possibles : Spécifique à la transaction

EXCHANGERATE Taux de change utilisé en cas de conversion de devise. S'applique

uniquement si vous facturez dans une devise secondaire. Si l'utilisateur choisit de payer dans une devise autre que la devise secondaire, la conversion a lieu sur son compte.

Nombre de caractères limite : une décimale qui ne dépasse pas 17 caractères, y compris la virgule décimale.

Valeurs possibles : Spécifique à la transaction

PAYMENTSTATUS Etat du paiement :

Completed : le paiement est terminé et les fonds ont été ajouté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 :

z no ne: pas de motif de mise en attente. z ad dress : 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 notificatio n

instantanée de paiement dans le s Préférences de votre Préférences.

z ec heck : 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é.

z in tl : 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.

z mu lti-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.

z ve rify : 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.

z ot her : 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.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 73

Liste de référence des méthodes et des champs de l'API NVP

Autorisation et collecte

ABLEAU A.11 Champs de la réponse Paiement DoExpressCheckout (suite)

Champ Description

REASONCODE Motif d'une annulation si TransactionType a la valeur reversal :

z no ne: aucun code de motif. z ch argeback : cette transaction a été annulée en raison d'un rejet de

débit de la part de votre client.

z gu arantee : cette transaction a été annulée car votre client a demandé à

faire jouer la garantie de remboursement.

z bu yer-complaint : cette transaction a été annulée car votre client a

déposé une réclamation concernant cette transaction.

z re fund : cette transaction a été annulée car vous avez remboursé le

client.

z ot her : cette transaction a été annulée pour un motif autre que celles

indiquées ci-dessus.

Autorisation et collecte

DoAuthorization

ABLEAU A.12 Paramètres DoAuthorization

Paramètre Description Obligatoire ?

METHOD Nom de l'API : DoAuthorization Oui TRANSACTIONID Valeur du numéro de transaction de la commande renvoyée par PayPal

Nombre de caractères limite : caractères d'un octet au maximum

AMT Montant à autoriser

Limites : la valeur est un nombre positif qui ne doit excéder $10.000 USD dans aucune devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule>(,) et le séparateur des milliers facultatif doit être un point (.).

TRANSACTIONENTITY Non CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

«Devises acceptées par PayPal» page 55. Par défaut : USD.

Oui

Non

74 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Autorisation et collecte

TABLEAU A.13 Champs de la réponse DoAuthorization

Field Description

TRANSACTIONID Numéro d'identification d'autorisation.

Nombre de caractères limite 19 caractères d'un octet.

AMT Montant spécifié dans la requête.

DoCapture

ABLEAU A.14 Paramètres DoCapture

Paramètre Description Obligatoire ?

METHOD Nom de l'API : DoCapture Oui AUTHORIZATIONID Numéro d'autorisation du paiement à collecter. Il s'agit du numéro de

transaction renvoyé par DoExpressCheckoutPayment ou DoDirectPayment.

Nombre de caractères limite : 19 caractères d'un octet au maximum.

AMT Montant à collecter

Limites : la valeur est un nombre positif qui ne doit excéder $10.000 USD dans aucune devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule >(,) et le séparateur des milliers facultatif doit être un point (.).

CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

«Devises acceptées par PayPal» page 55. Par défaut : USD.

COMPLETETYPE La valeur Comple te "> indique s'il s'agit de la dernière collecte que vous

avez l'intention d'exécuter. La valeur NotComplete indique que vous avez l'intention d'exécuter des

collectes supplémentaires

REMARQUE : si vous conservez la valeur Complete, tout montant

restant de la transaction initiale autorisée est automatiquement annulé et toutes les autorisations ouvertes restantes sont annulées.

Nombre de caractères limite : 12 caractères alphanumériques d'un octet.

Oui

Non

Oui

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 75

Liste de référence des méthodes et des champs de l'API NVP

Autorisation et collecte

ABLEAU A.14 Paramètres DoCapture (suite)

Paramètre Description Obligatoire ?

INVNUM Votre numéro de facture ou un autre numéro d'identification affiché pour le

Non

marchand ou le client dans son historique des transactions

REMARQUE : cette valeur de on DoCapture remplace la valeur

précédemment définie pour DoAuthorization.

REMARQUE : la valeur n'est enregistrée que si l'autorisation que vous

collectez est une autorisation de commande et pas une autorisation de base.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

NOTE Note d'information sur le règlement concerné, envoyée par email à

Non

l'émetteur du paiement et qui apparaît dans l' h istorique de ses transactions.

Nombre de caractères limite : 255 caractères d'un octet

ABLEAU A.15 Champs de la réponse DoCapture

Champ Description

AUTHORIZATIONID Numéro d'autorisation spécifié dans la requête.

Nombre de caractères limite : 19 caractères d'un octet au maximum

TRANSACTIONID Numéro de transaction unique du paiement.

Nombre de caractères limite : 17 caractères d'un octet.

PARENTTRANSACTIONID Numéro de transaction parent ou liée. Ce champ est rempli pour les types de

transaction suivants :

z Annulation. Collecte d'une transaction autorisée. z Annulation. Nouvelle autorisation d'une transaction. z Collecte d'une commande. La valeur de ParentTransactionID correspond

au OrderID initial.

z Autorisation d'une commande. La valeur de ParentTr ansactio nID

correspond au OrderID initial.

z Collecte d'une autorisation de commande. z Annulation d'une commande. La valeur de ParentTransaction ID

correspond au OrderID initial.

Nombre de caractères limite : 16 chiffres au format xxxx-xxxx-xxxx-xxxx

RECEIPTID Numéro d'avis de réception

Nombre de caractères limite : 16 chiffres au format xxxx-xxxx-xxxx-xxxx

TRANSACTIONTYPE

Type de transaction

z cart z express-checkout

Nombre de caractères limite 15 caractères d'un octet.

PAYMENTTYPE Indique si le paiement est imm édi a t ou différé

Nombre de caractères limite sept caractères d'un octet

76 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Autorisation et collecte

ABLEAU A.15 Champs de la réponse DoCapture (suite)

Champ Description

ORDERTIME Horodatage du paiement. Exemple :2006-08-15T17:23:15Z. AMT Montant final facturé, incluant les frais d'expédition, de

livraison et de TVA de vos Préférences du marchand.

FEEAMT Montant de la commission de PayPal facturée pour la

transaction

SETTLEAMT Montant déposé sur votre compte PayPal en cas de conversion

de devise

TAXAMT TVA appliquée à la transaction, le cas échéant EXCHANGERATE ExTaux de change utilisé en cas de conversion de devise. S'applique

uniquement si vous facturez dans la devise secondaire de l'utilisateur. Si l'utilisateur choisit de payer dans une devise autre que la devise secondaire, la conversion a lieu sur son compte.

Nombre de caractères limite : multiplicateur décimal.

PAYMENTSTATUS

Etat du paiement. Etat du paiement :

z None : aucun état. z Canceled-Reversal : indique qu'une contre-opération a été

annulée. Par exemple, si un litige avec le client a été réglé en votre faveur et que les fonds de la transaction annulée vous ont été remboursés.

z Completed : le paiement est terminé et les fonds ont été ajoutés au

solde de votre compte.

z Denied : vous avez refusé le paiement. Cela se produit si le paiement

était précédemment en attente pour l'une des raisons décrites dans l'élément PendingReason.

z Expired : la durée d'autorisation pour ce paiement a expiré. z Failed : le paiement a échoué. Cela se produit uniquement si le

paiement a été effectué à partir du compte bancaire de votre client.

z Pending : le paiement est en attente. Pour en savoir plus, reportezvous

au champ PendingReason.

z Refunded : vous avez remboursé le paiement. z Reversed : un paiement a été annulé en raison d'un rejet de débit ou

d'un autre type de contre-opération. Les fonds ont été retirés du solde de votre compte et rendus à l'acheteur. La raison de l'annulation est spécifiée dans l'élément ReasonCode.

z Processed : un paiement a été accepté. z Voided : l'autorisation pour cette transaction a été annulée.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 77

Liste de référence des méthodes et des champs de l'API NVP

Autorisation et collecte

DoReauthorization

TABLEAU A.16 Paramètres de la requête DoReauthorization

Paramètre Description Obligatoire ?

METHOD Nom de l’API : DoReauthorization Oui AUTHORIZATIONID Valeur du numéro d'une transaction préalablement autorisée, renvoyée par

PayPal Nombre de caractères limite : 19 caractères d'un octet au maximum

AMT Montant à autoriser à nouveau.

Limites : la valeur est un nombre positif qui ne doit excéder $10.000 USD dans aucune devise. Pas de symbole de devise. Doit comporter deux positions décimales, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif doit être un point (.).

CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

«Devises acceptées par PayPal» page 55. Par défaut : USD.

ABLEAU A.17 Champs de la réponse DoReauthorization

Champ Description

AUTHORIZATIONID Nouveau numéro d'autorisation

Nombre de caractères limite : 19 caractères d'un octet.

DoVoid

Oui

Non

ABLEAU A.18 Paramètres de la requête DoVoid Request

Obligatoir

Paramètre Description

METHOD Nom de l’API : DoVoid Oui AUTHORIZATIONID Valeur du numéro d'autorisation initial renvoyée par un produit PayPal.

IMPORTANT : si vous annulez une transaction qui a fait l'objet d'une

nouvelle autorisation, utilisez le numéro de l'autorisation initiale, pas celui de la nouvelle autorisation.

Nombre de caractères limite : 19 caractères d'un octet

NOTE Note d'information sur cette annulation, envoyée par email à l'émetteur du

paiement et qui apparaît dans l'historique de ses transactions. Nombre de caractères limite : 255 caractères d'un octet.

e ?

Oui

Non

78 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

RefundTransaction

TABLEAU A.19 Champs de la réponse DoVoid

Champ Description

AUTHORIZATIONID Numéro d'autorisation spécifié dans la requête.

Nombre de caractères limite : 19 Numéro caractères d'un octet.

RefundTransaction

ABLEAU A.20 Paramètres de la requête RefundTransaction

Paramètre Description Obligatoire ?

METHOD Nom de l'appel API : RefundTransaction Oui TRANSACTIONID Identifiant unique d'une transaction.

Oui

Nombre de caractères limite : 17 numéro caractères d'un octet.

REFUNDTYPE Type de remboursement effectué.

z Au tre z Fu ll z Pa rtial

AMT Montant du remboursement.

Oui

Non

Edoit être défini si RefundType is Partial.

REMARQUE : si RefundType a la valeur Full, ne définissez pas

Amount

NOTE Mémo perso nnalisé concernant le remboursement.

Non

Nombre de caractères limite : 255 caractères alphanumériques d'un octet.

ABLEAU A.21 Champs de la réponse DoRefund

Champ Description

REFUNDTRANSACTIONID Numéro de transaction unique du remboursemen t.

Nombre de caractères limite : 17 Numéro caractères d'un octet.

NETREFUNDAMT Montant soustrait du solde PayPal du destinataire initial du paiement pour

effectuer ce remboursement.

FEEREFUNDAMT Commission sur transaction remboursée au destinataire initial du paiement. GROSSREFUNDAMT Somme d'argent remboursée au payeur initial.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 79

Liste de référence des méthodes et des champs de l'API NVP

TransactionSearch

Avec TransactionSearch vous devez toujours définir le champ StartDate. Autre comportement :

z Lorsqu'elle est définie, la valeur de TransactionID remplace celles de tous les autres

champs (y compris le champ StartDate obligatoire).

z La définition d'autres éléments s'ajoute à l'existant ou peut modifier les critères de

recherche.

TransactionSearch renvoie jusqu'à 100 correspondances. Les correspondances partielles avec le système de vérification d'adresse s'affichent. Par exemple, l'attribution de la valeur « Jess » à l'élément FirstName de TransactionSearchRequest renvoie des résultats tels que « Jessica » et « Jesse ».

L'élément renvoyé le plus important est TransactionID que vous pouvez transmettre à GetTransactionDetails afin de récupérer toutes les informations disponibles sur une transaction spécifique.

TABLEAU A.22 Paramètres de TransactionSearch Request

Paramètre Description Obligatoire

METHOD Nom de l'appel API : TransactionSearch Oui STARTDATE Date de transaction la plus ancienne à partir de laquelle lancer la recherche.

REMARQUE : aucun caractère générique n'est autorisé. La valeur doit

être au format UTC/GMT.

ENDDATE Date de transaction la plus récente à inclure dans la recherche. Non EMAIL Recherche par adresse email de l'acheteur.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

RECEIVER Recherche par adresse email du bénéficiaire. Si le compte marchand

possède un seul email, celui-ci sera l'email principal. Peut également être un email autre que l'email principal.

RECEIPTID Recherche par numéro d'avis de réception du compte PayPal facultatif. Non TRANSACTIONID Recherche par numéro de transaction.

REMARQUE : les résultats renvoyés proviennent des registres des

transactions du marchand.

Nombre de caractères limite : 19 caractères d'un octet au maximum

INVNUM Recherche par clé de demande de paiement que vous avez définie pour la

transaction initiale. Ce champ recherche les objets vendus par le marchand dans les registres et non les objets achetés.

REMARQUE : aucun caractère générique n'est autorisé.

Oui

Non

Nombre de caractères limite : 127 caractères d'un octet au maxim um

80 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

TransactionSearch

ABLEAU A.22 Paramètres de TransactionSearch Request (suite)

Paramètre Description Obligatoire

ACCT Recherche par numéro de carte bancaire que vous avez défini pour la

Non transaction initiale. Ce champ recherche les objets vendus par le marchand dans les registres et non les objets achetés.

REMARQUE : aucun caractère générique n'est autorisé.

Nombre de caractères limite : entre 11 et 25 caractères numériques d'un octet. Les signes de ponctuation spéciaux, par exemple les tirets ou les espaces, sont ignorés.

SALUTATION Formule d'appel de l'acheteur.

Non Nombre de caractères limite : 20 caractères d'un octet.

FIRSTNAME Prénom de l'acheteur.

Non Nombre de caractères limite : 25 caractères d'un octet.

MIDDLENAME Deuxième prénom de l'acheteur.

Non Nombre de caractères limite : 25 caractères d'un octet.

LASTNAME Nom de l'acheteur.

Non Nombre de caractères limite : 2025 caractères d'un octet.

SUFFIX Suffixe du payeur.

Non Nombre de caractères limite : 12 caractères d'un octet.

AUCTIONITEMNUMBER Recherche par numéro d'enchère des biens achetés. Non

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 81

Liste de référence des méthodes et des champs de l'API NVP

TransactionSearch

ABLEAU A.22 Paramètres de TransactionSearch Request (suite)

Paramètre Description Obligatoire

TRANSACTIONCLASS Recherche par classification de la transaction.

REMARQUE : certains types de classes de transactions possibles ne

peuvent pas être recherchés avec ce champ. Par exemple, vous ne pouvez pas rechercher les virements bancaires.

z All : toutes les classifications de transactions z S ent : uniquement les paiements envoyés z R eceived : uniquement les paiements reçus z M assPay : uniquement les paiements groupés z M oneyRequest : uniquement les demandes de paiement z F undsAdded : uniquement les fonds crédités au solde z F undsWithdrawn : uniquement les fonds débités du solde z R eferral : uniquement les transactions impliquant des parrainages z Fee : uniquement les transactions impliquant des commissions z S ubscription : uniquement les transactions impliquant des

abonnements

z D ividend : uniquement les transactions impliquant des dividendes z B illpay : uniquement les transactions impliquant des transactions

BillPay

z R efund : uniquement les transactions impliquant des fonds z C urrencyConversions : uniquement les transactions impliquant des

conversions de devises

z B alanceTransfer : uniquement les transactions impliquant des

transferts de solde

z R eversal : uniquement les transactions impliquant des annulations

BillPay

z S hipping : uniquement les transactions impliquant des frais d'envoi

UPS

z B alanceAffecting : uniquement les transactions affectant le solde

du compte

z E Check : uniquement les transactions impliquant des chèques

électroniques

Non

AMT Recherche par montant de transaction. Non

82 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

TransactionSearch

ABLEAU A.22 Paramètres de TransactionSearch Request (suite)

Paramètre Description Obligatoire

STATUS Recherche par état de transaction :

z P ending : le paiement est en attente. Le motif spécifique de mise en

attente du paiement est renvoyé par le champ PendingReason de l'API GetTransactionDetails.

z P rocessing : le paiement est en cours de traitement. z S uccess : le paiement est effectué et les fonds ont été ajoutés au solde

de votre compte.

z D enied : vous avez refusé le paiement. Cela se produit uniquement si

le paiement a été précédemment mis en attente.

z R eversed : un paiement a été annulé en raison d'un rejet de débit ou

d'un autre type de contre-opération. Les fonds ont été retirés du solde de votre compte et rendus à l'acheteur.

ABLEAU A.23 Champs de la réponse TransactionSearch

Champ Description

L_TIMESTAMPn Date et heure (au format UTC/GMT) de la transaction

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_TIMESTAMP0, L_TIMESTAMP1 , et ainsi de suite.

L_TIMEZONEn Fuseau horaire de la transaction

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_TIMEZONE0, L_TIMEZONE 1, et ainsi de suite.

Non

L_TYPEn Type de la transaction

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_TYPE0, L_TYPE1, et ainsi de suite.

L_EMAILn Adresse email du payeur ou du destinataire du paiement (le « bénéficiaire du paiement »).

Si le montant du paiement est positif, ce champ indique le destinataire des fonds. S'il est négatif, ce champ indique le client qui paie.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_EMAIL0, L_EMAIL1, et ainsi de suite.

L_NAMEn Affiche le nom du payeur

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_NAME0, L_NAME1, et ainsi de suite.

L_TRANSACTIONIDn Numéro de transaction du vendeur

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_TRANSACTIONID0, L_TRANSACTIONID1, et ainsi de suite.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 83

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.23 Champs de la réponse TransactionSearch (suite)

Champ Description

L_STATUSn Etat de la transaction.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_STATUS0, L_STATUS1, et ainsi de suite.

L_AMTn Montant total hors taxe débité, y compris les frais d'expédition et de livraison et les taxes

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_AMT0, L_AMT1, et ainsi de suite.

L_FEEAMTn Frais débités par PayPal pour la transaction

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_FEEAMT0, L_FEEAMT1, et ainsi de suite.

L_NETAMTn Montant net de la transaction.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_NETAMT0, L_NETAMT1, et ainsi de suite.

GetTransactionDetails

ABLEAU A.24 Paramètres de la requête GetTransactionDetails

Paramètre Description Obligatoire ?

METHOD Nom de l'API : GetTransactionDetails Oui TRANSACTIONID Identifiant unique d'une transaction.

REMARQUE : les détails de certains types de transactions ne peuvent

pas être extraits avec GetTransactionDetails. Par exemple, vous ne pouvez pas obtenir les détails des virements bancaires.

Nombre de caractères limite : 17 caractères alphanumériques d'un octet.

ABLEAU A.25 Champs de la réponse GetTransactionDetails

Paramètre Description

RECEIVERBUSINESS Adresse email ou numéro de compte du destinataire du paiement (le vendeur).

Equivalent à Receiver si le paiement est envoyé au compte principal. Nombre de caractères limite : 127 caractères alphanumériques d'un octet

RECEIVEREMAIL Adresse email principale du destinataire du paiement (le vendeur).

Si vous êtes le destinataire du paiement et que celui-ci est envoyé à une adresse email autre que l'adresse principale, la valeur de Receiver reste votre adresse email principale.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

Oui

84 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

RECEIVERID Numéro de compte unique du destinataire du paiem ent (le vendeur). Cette valeur est

identique à celle du code parrainage du destinataire.

EMAIL Adresse email du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

PAYERID Numéro client unique.

Nombre de caractères limite : 13 caractères alphanumériques d'un octet.

PAYERSTATUS Etat de l'adresse email du payeur :

Vérifié Non-Vérifié

FIRSTNAME Prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

LASTNAME Nom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

MIDDLENAME Deuxième prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

PAYERBUSINESS Raison sociale du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

SHIPTOCOUNTRYCODE Pays de résidence de l'expéditeur du paiement, indiqué par un code pays ISO 3166 à

deux caractères. Nombre de caractères limite : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

SALUTATION Formule d'appel du payeur.

Nombre de caractères limite : 20 caractères d'un octet.

SUFFIX Suffixe du payeur.

Nombre de caractères limite : 12 caractères d'un octet.

ADDRESSOWNER Société eBay qui gère cette adresse. ADDRESSSTATUS Etat de l'adresse enregistrée chez PayPal :

None Confirmed Unconfirmed

SHIPTOCITY Nom de la ville.

Nombre de caractères limite : 120 caractères alphanumériques d'un octet.

Annexe F, «Codes pays».

SHIPTONAME Nom de la personne associée à cette adresse.

Nombre de caractères limite : 32 caractères alphanumériques d'un octet.

SHIPTOPHONENUM Numéro de téléphone associé à cette adresse.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 85

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

SHIPTOZIP Code postal SHIPTOSTATE Etat ou province.

Nombre de caractères limite : 120 caractères alphanumériques d'un octet Requis pour les adresses américaines (USA) seulement.

SHIPTOSTREET Première adresse postale.

Nombre de caractères limite : 300 caractères alphanumériques d'un octet.

SHIPTOSTREET2 Seconde adresse postale.

Nombre de caractères limite : 300 caractères alphanumériques d'un octet.

PARENTTRANSACTIONID Transaction initiale à laquelle cette transaction est associée. Ce champ est rempli pour

les types de transaction suivants :

z Annulation z Collecte d'une transaction autorisée. z Nouvelle autorisation d'une transaction. z Collecte d'une commande. La valeur de ParentTransactionID correspond au

OrderID initial.

z Autorisation d'une commande. La valeur de Parent TransactionID correspond

au OrderID initial.

z Collecte d'une autorisation de commande. z Annulation d'une commande. La valeur de ParentTra nsactionID correspond au

OrderID initial.

Nombre de caractères limite : 19 caractères d'un octet.

TRANSACTIONID Numéro de transaction de PayPal.

Nombre de caractères limite : 19 caractères d'un octet.

RECEIPTID Numéro d'avis de réception

Nombre de caractères limite : 16 chiffres au format xxxx-xxxx-xxxx-xxxx format

TRANSACTIONTYPE Ty pe de transaction

cart : transaction créée par le client via la fonction Panier de PayPal. send-money : transaction créée par le client à partir de l'onglet Paiement du site

PayPal. web-accept : transaction créée par le client via les logos malins Acheter maintenant,

Dons ou Enchères. subscr-*: transaction créée par le client via la fonction Abonnement. eot signifie «

fin de la durée d'abonnement ».

merch-pmt : paiement pré-approuvé. mass-pay: Transaction créée via MassPay. virtual-terminal : transaction créée via le terminal virtuel du marchand.

PAYMENTTYPE Indique si le paieme nt est immé di at ou différé.

Nombre de caractères limite : sept caractères d'un octet.

ORDERTIME Date et heure du paiement.

86 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

AMT Montant total du paiement du client, avant soustraction des commissions sur les

transactions.

FEEAMT Commissions sur transaction associées au paiement. SETTLEAMT Montant déposé sur le solde principal du compte après conversion automatique de la

devise (par le biais de vos Payment Receiving Prefer ences) ou conversion manuelle (en acceptant manuellement un paiement). Ce montant est calculé après évaluation des frais et des taxes.

TAXAMT Montant des taxes pour la transaction. EXCHANGERATE Taux de change pour la transaction. PAYMENTSTATUS Etat du paiement.

Etat du paiement :

z No ne : aucun état. z Ca nceled-Reversal : indique qu'une contre-opération a été annulée. Par

exemple, si un litige avec le client a été réglé en votre faveur et que les fonds de la transaction annulée vous ont été remboursés.

z Co mpleted : le paiement est terminé et les fonds ont été ajoutés au solde de votre

compte.

z De nied : vous avez refusé le paiement. Cela se produit si le paiement était

précédemment en attente pour l'une des raisons décrites dans l'élément PendingReason.

z Ex pired : la durée d'autorisation pour ce paiement a expiré. z Fa iled : le paiement a échoué. Cela se produit uniquement si le paiement a été

effectué à partir du compte bancaire de votre client.

z Pe nding : le paiement est en attente. Pour en savoir plus, reportez-vous au champ

PendingReason.

z Re funded : vous avez remboursé le paiement. z Re versed : un paiement a été annulé en raison d'un rejet de débit ou d'un autre type

de contre-opération. Les fonds ont été retirés du solde de votre compte et rendus à l'acheteur. La raison de l'annulation est spécifiée dans l'élément ReasonCode.

z Pr ocessed : un paiement a été accepté. z Vo ided : l'autorisation pour cette transaction a été annulée.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 87

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

PENDINGREASON REMARQUE : PendingReason est renvoyé dans la réponse uniquement si

PaymentStatus a la valeur Pending.

Motif pour lequel le paiement est en attente :

z no ne: pas de motif de mise en attente. z ad dress : 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 pai ement dans les Pré férences de votre Préférences.

z ec heck : 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é.

z in tl : 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.

z mu lti-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.

z ve rify : 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.

z ot her : 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.

REASONCODE Motif d'une annulation si TransactionType a la valeur reversal :

z no ne: aucun code de motif. z ch argeback : cette transaction a été annulée en raison d'un rejet de débit de la part

de votre client.

z gu arantee : cette transaction a été annulée car votre client a demandé à faire jouer

la garantie de remboursement.

z bu yer-complaint : cette transaction a été annulée car votre client a déposé une

réclamation concernant cette transaction.

z re fund : cette transaction a été annulée car vous avez remboursé le client. z ot her : cette transaction a été annulée pour un motif autre que celles indiquées ci-

dessus.

INVNUM Numéro de facture défini dans la transaction initiale.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

CUSTOM Champ personnalisé défini dans la transaction init iale.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

NOTE Mémo saisi par votre client dans le champ note des paiements sur site marchand de

PayPal. Nombre de caractères limite : 255 caractères alphanumériques d'un octet.

SALESTAX Montant des taxes débitées pour le paiement.

88 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

GetTransactionDetails

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

L_DESCn Nom de l'objet défini par vous ou saisi par le client. S'il s'agit d'une transaction

effectuée via le Panier, PayPal ajoute le numéro de l'objet à la variable HTML item_name. Par exemple, item_name1, item_name2, etc.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet Il est conseillé d’organiser ces paramètres de manière séquentielle en

commençant par 0, par exemple, L_DESC0, L_DESC1, et ainsi de suite.

L_NUMBERn Numéro de l'objet que vous avez défini. S'il s'agit d'une transaction effectuée via le

Panier, PayPal ajoute le numéro de l'objet à la variable HTML item_number. Par exemple, item_number1, item_number2, etc.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet Il est conseillé d’organiser ces paramètres de manière séquentielle en

commençant par 0, par exemple, L_NUMBER0, L_NUMBER1, et ainsi de suite.

L_QTYn Quantité définie par vous ou saisie par le client.

Nombre de caractères limite : pas de limite.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_QTY0, L_QTY1, et ainsi de suite.

L_AMTn Coût de l'objet.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_AMT0, L_AMT1, et ainsi de suite.

L_OPTIONSn Options des objets PayPal po ur le Panier.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_OPTIONS0, L_OPTIONS1, et ainsi de suite.

SUBSCRIPTIONID Numéro généré par PayPal pour l'abonné.

Nombre de caractères limite : pas de limite.

SUBSCRIPTIONDATE Date de début de l'abonnement. EFFECTIVEDATE Date d'entrée en vigueur de la modification de l'abonnement. RETRYTIME Date à laquelle PayPal va à nouveau essayer le paiement d'abonnement qui a échoué. USERNAME Identifiant généré par PayPal et donné à l'abonné pour accéder à l'abonnement.

Nombre de caractères limite : 64 caractères alphanumériques d'un octet

PASSWORD Mot de passe généré par PayPal et donné à l'abonné pour accéder à l'abonnement. Pour

des raisons de sécurité, la valeur du mot de passe est hachée. Nombre de caractères limite : 128 caract ères al phanumériques d'un octet

RECURRENCES Le nombre de versements qui auro nt li eu au tarif st andard.

Nombre de caractères limite : pas de limite.

REATTEMPT Indique si de nouvelles tentatives doivent être effectuées en cas d'échec de paiement.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 89

Liste de référence des méthodes et des champs de l'API NVP

Paiement groupé

ABLEAU A.25 Champs de la réponse GetTransactionDetails (suite)

Paramètre Description

RECURRING Indique s'il y a une base récurrente de facturation.

1 = Oui

PERIOD Durée pendant laquelle l'abonné sera débité.

Nombre de caractères limite : pas de limite.

BUYERID Identification d'enchère du client. CLOSINGDATE Date de clôture des enchères. MULTIITEM Compteur utilisé pour les paiements pour enchères de plusieurs objets.

Paiement groupé

ABLEAU A.26 Paramètres MassPay

Paramètre Description Obligatoire ?

METHOD Nom de l'API : MassPay Oui RECEIVERTYPE Indique comment identifier les destinataires des paiements pour tous les

éléments : à l'aide de EmailAddress (L_EMAIL

UserID (L_RECEIVERID_ L_AMTn Montant du paiement. Oui CURRENCYCODE Un code de devise à trois caractères pour une des devises répertoriées dans

n dans chaque objet).

n dans chaque objet) or by

Oui

«Devises acceptées par PayPal» page 55 Par défaut : USD.

L_EMAILn Adresse email du destinataire.

REMARQUE : vous devez préciser le paramètre L_EMAILn ou

L_RECEIVERIDn, mais vous ne pouvez pas les associer. Utilisez

uniquement l'un ou l'autre, mais pas les deux, dans la même requête.

Nombre de caractères limite 127 caractères d’un octet maximum.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_EMAIL0,

L_EMAIL1, Ces paramètres devraient êtreet ainsi de suite.

L_RECEIVERIDn Numéro de compte unique du client PayPal. Cette valeur correspond à la

valeur de PAYERID renvoyée par GetTransactionDetails.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_RECEIVERID0, L_RECEIVERID1, Ces paramètres devraient êtreet ainsi de suite.

Dépend de la

RECEIVERTYPE

90 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.26 Paramètres MassPay (suite)

Paramètre Description Obligatoire ?

L_UNIQUEIDn Numéro de transaction spécifique permettant d'assurer le suivi dans un

système comptable.

Nombre de caractères limite 30 caractères d’un octet. Aucun espace n'est

autorisé.

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_UNIQUEID0, L_UNIQUEID1, ces paramètres devraient êtreet ainsi de suite.

L_NOTEn Remarque personnalisée pour chaque destinataire.

Nombre de caractères limite : 4,000 caractères alphanumériques d'un octet

Il est conseillé d’organiser ces paramètres de manière séquentielle en commençant par 0, par exemple, L_NOTE0,

L_NOTE1, Ces paramètres devraient êtreet ainsi de suite.

EMAILSUBJECT Ligne Objet de l'email envoyé par PayPal une fois la transaction terminée.

Cette ligne est la même pour tous les destinataires..

Nombre de caractères limite : 255 caractères alphanumériques d'un octet

ABLEAU A.27 Champs de la réponse MassPay Response

Les champs de la réponse sont les champs d'en-tête de réponse standard. Voir [successResponseHeader].

Non

Paiements récurrents

SetCustomerBillingAgreement

SetCustomerBillingAgreementRequest

Le message SetCustomerBillingAgreementRequest se compose des champs identifiés dans Tableau A.28.

ABLEAU A.28 Champs de SetCustomerBillingAgreementRequest

Nom Description et type de données Obligatoire

METHOD Nom de l'API : SetCustomerBillingAgreement Oui BILLINGTYPE Le type d'autorisation de facturation devant être établie entre le

marchand et le client. Dans le cas de paiements récurrents, la valeur doit être RecurringPayments.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 91

Oui

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.28 Champs de SetCustomerBillingAgreementRequest (suite)

Nom Description et type de données Obligatoire

DESC Description des biens ou des services associés à l'autorisation de

facturation. PayPal vous recommande d'inclure dans la description un court

récapitulatif des conditions générales d'autorisation de facturation. Nombre de caractères limite : 127 caract ères al phanumériques d'un

octet

CUSTOM Champ d'annotation pe rsonnalisé que vous utilisez librement.

Nombre de caractères limite : 256 caract ères al phanumériques d'un octet

PAYMENTTYPE Indique le type paiement PayPal dont vous avez besoin pour le paiement

récurrent ou pour l'autorisation de facturation. Dans le cas de paiements récurrents, la valeur doit être InstantOnly.

RETURNURL URL vers laquelle le navigateur du client est renvoyé après avoir choisi

de payer avec PayPal.

REMARQUE : PayPal recommande que la valeur corresponde à la

page de vérification finale sur laquelle le client confirme l'autorisation de facturation.

Nombre de caractères limite : pas de limite.

CANCELURL URL vers laquelle le client est renvoyé s'il n'approuve pas l'utilisation

de PayPal pour vous payer.

REMARQUE : PayPal recommande que la valeur corresponde à la

page initiale sur laquelle le client a choisi de payer avec PayPal ou d'établir une autorisation de facturation.

Non

Oui

Nombre de caractères limite : pas de limite.

92 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.28 Champs de SetCustomerBillingAgreementRequest (suite)

Nom Description et type de données Obligatoire

LOCALECODE Paramètre régional des pages af fichées par PayPal pendant la procédure

de paiement. Nombre de caractères limite : N'im porte quel code pays de deux

caractères. Les codes pays de deux caractères suivants sont pris en charge par

PayPal :

z AU z DE z FR z IT z GB z ES z US

Toute autre valeur sera remplacée par défaut par US.

REMARQUE : dans le cas de paiements récurrents, le paramètre

régional doit être US.

REMARQUE : pour consulter la liste des codes pays, reportez-vous

à l’

Annexe F, «Codes pays».

PAGESTYLE Détermine le style personnalisé des pages de paiement associées à ce

Nombre de caractères limite : 30 caractères alphabétiques d'un octet.

Non

HDRIMG URL de l'image que vous souhaitez voir apparaître dans la partie

Non supérieure gauche de la page de paiement. La taille maximale de l'image est de 750 pixels en largeur et de 90 pixels en hauteur. PayPal vous recommande de fournir une image stockée sur un serveur sécurisé (https).

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

HDRBORDERCOLOR Définit la couleur de bordure de l'en-tête de la page de paiement. La

Non bordure est un périmètre de 2 pixels autour de l'espace d'en-tête, qui dispose d'une taille de 750 pixels de large sur 90 pixels de haut.

Nombre de caractères limite : co de couleur hexadécimal HTML de six caractères en ASCII.

HDRBACKCOLOR Définit la couleur d'arrière-plan de l'en-tête de la page de paiement.

Non Nombre de caractères limite : co de couleur hexadécimal HTML de six

caractères en ASCII.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 93

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.28 Champs de SetCustomerBillingAgreementRequest (suite)

Nom Description et type de données Obligatoire

PAYFLOWCOLOR Définit la couleur d'arrière-plan de la page de paiement.

Nombre de caractères limite : co de couleur hexadécimal HTML de six caractères en ASCII.

EMAIL Adresse email de l'acheteur entrée pendant le paiement. PayPal utilise

cette valeur pour pré-remplir la partie réservée à l'inscription pour l'adhésion à PayPal de la page de connexion PayPal.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

SetCustomerBillingAgreementResponse

Non

Le message SetCustomerBillingAgreementRequest se compose des champs identifiés dans Tableau A.29.

ABLEAU A.29 Champs de SetCustomerBillingAgreementResponse

Elément Description et type de données

TOKEN Un jeton horodaté qui identifie cette transaction de manière unique en vue d'appels

API ultérieurs.

REMARQUE : le jeton expire au bout de trois heures.

Nombre de caractères limite : 20 caractères d'un octet.

GetBillingAgreementCustomerDetails

GetBillingAgreementCustomerDetails Request

Le message GetBillingAgreementCustomerDetailsRequest se compose des champs identifiés dans Tableau A.30.

ABLEAU A.30 Champs de GetBillingAgreementCustomerDetailsRequest

Elément Description et type de données Obligatoire

METHOD Nom de l’API : GetBillingAgreementCustomerDetails Oui TOKEN Le jeton horodaté renvoyé dans la réponse

SetCustomerBillingAgreement response.

REMARQUE : le jeton expire au bout de trois heures.

Nombre de caractères limite : 20 Numéro caractères d'un octet.

Oui

94 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Réponse GetBillingAgreementCustomerDetails

Le message GetBillingAgreementCustomerDetailsResponse se compose des champs identifiés dans Tableau A.31

TABLEAU A.31 Champs de GetBillingAgreementCustomerDetailsResponse

Elément Description et type de données

EMAIL Adresse email du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

PAYERID Numéro client unique.

Nombre de caractères limite : 13 caractères alphanumériques d'un octet.

PAYERSTATUS Etat de l'adresse email du payeur :

Vérifié Non-Vérifié

SALUTATION Formule d'appel du payeur.

Nombre de caractères limite : 20 caractères d'un octet.

Paiements récurrents

FIRSTNAME Prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

MIDDLENAME Deuxième prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

LASTNAME Nom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

SUFFIX Suffixe du payeur.

Nombre de caractères limite : 12 caractères d'un octet.

SHIPTOCOUNTRYCODE Pays de résidence de l'expéditeur du paiement, ind iqu é par un code pays ISO 3166 à

deux caractères. Nombre de caractères limite : deux caractères d'un octet. Pour consulter la liste des codes pays, reportez-vous à l’

PAYERBUSINESS Raison sociale du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

Adresse de livraison Reportez-vous à la section

GetExpressCheckoutDetails », page 66

Tableau A.8 « Champs de la réponse

Annexe F, «Codes pays».»

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 95

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

CreateRecurringPaymentsProfile

Requête CreateRecurringPaymentsProfile

Le message CreateRecurringPaymentsProfileRequest se compose des champs identifiés dans Tableau A.32.

TABLEAU A.32 Requête CreateRecurringPaymentsProfile

Nom Description et type de données Obligatoire

METHOD Nom de l’API : CreateRecurringPaymentsProfile Oui TOKEN Jeton horodaté dont la valeur a été renvoyée par la réponse

SetCustomerBillingAgreement.

REMARQUE : le jeton expire au bout de trois heures.

Nombre de caractères limite : 20 Numéro caractères d'un octet.

SUBSCRIBERNAME Nom de la personne associée à cette adresse.

Sinon, le nom spécifié dans le compte PayPal de l'abonné est utilisé. Nombre de caractères limite : 32 Numéro caractères d'un octet.

Adresse de livraison

Tableau A.5 « Adresse de livraison (facultatif) », page 64

PROFILESTARTDATE La date de début de facturation pour ce profil.

PROFILEREFERENCE La référence unique ou le numéro de facture du marchand.

L'adresse de livraison de l'acheteur,le cas échéant. Si l’adresse n’est pas spécifiée, l’adresse du compte PayPal de l'abonné sera utilisée.

Pour en savoir plus, reportez-vous au

livraison (facultatif) », page 64

REMARQUE : l'adresse de livraison est facultative mais si vous

l'incluez, certains champs doivent être saisis.

Doit être une date valable, de format AAAA-MM-JJ.

REMARQUE : l'activation des préférences peut prendre jusqu'à 24

heures.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

Tableau A.5 « Adresse de

Oui

Non

Oui

Non

DESC Description du paiement récurrent.

Nombre de caractères limite : 127 caractères alphanumériques d'un octet.

Non

96 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.32 Requête CreateRecurringPaymentsProfile (suite)

Nom Description et type de données Obligatoire

TRIALBILLINGPERIOD Unité de facturation pour cette période.

Une des valeurs suivantes :

z Da y z We ek z Se miMonth z Mo nth z Ye ar

Pour créer un période d'essai TRIALBILLINGPERIOD est obligatoire. Si ce n'est pas le cas, il est également facultatif.

Il est possible de créer seulement une période d'essai par préférence.

REMARQUE : la combinaison deTRIALBILLINGPERIOD a et

deTRIALBILLINGFREQUENCY ne doit pas excéder une année.

TRIALBILLINGFREQUENCY Le nombre de périodes de facturation constituant un cycle de

facturation. Pour créer un période d'essai , TRIALBILLINGFREQUENCY est

obligatoire. Si ce n'est pas le cas, il est également facultatif.

REMARQUE : TRIALBILLINGFREQUENCY est ignoré si

TRIALBILLINGPERIOD est SemiMonth. Si TRIALBILLINGFREQUENCY est SemiMonth , la facturation est

effectuée le 1er et le 15 du mois.

La combinaison deTRIALBILLINGPERIOD et deTRIALBILLINGFREQUENCY ne pouvant excéder une année, les valeurs maximales de TRIALBILLI NGFREQUENCY sont:

z Day: 365 z Week: 52 z SemiMonth: N/A z Mon th: 12 z Year: 1

Voir la description

TRIALTOTALBILLINGCYCLES

z Le nombre de cycles de facturation avant que la facturation standard

ne commence.

z Si aucune valeur n'est spécifiée ou si la valeur est 0, la période se

Voir la description

poursuit jusqu'à annulation ou désactivation des préférences.

z Si la valeur est supérieure à 0, la période finira au terme de la

période d'essai et se poursuivra à BillingFrequency pour T otalBillingCycles cycles.

Pour créer un période d'essai, TRIALTOTALBILLINGCYCLE S est obligatoire. Si ce n'est pas le cas, il est également facultatif.

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 97

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.32 Requête CreateRecurringPaymentsProfile (suite)

Nom Description et type de données Obligatoire

TRIALAMT Montant de la facturation pour chaque période.

Pour créer une période d'essai, TRIALAMT est obligatoire. Si ce n'est pas le cas, il est également facultatif.

Nombre de caractères limite : ne dépasse $10,000 USD dans aucune devise. Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

TRIALSHIPPINGAMT Montant de la livraison par cycle de facturation pour chaque période

d'essai. Nombre de caractères limite : ne dépasse $10,000 USD dans aucune

devise. Pas de symbole de devise. Quelle que soit la devise, le séparateur décimal doit être une virgule (,) et le séparateur des milliers facultatif un point (.). Equivalent à neuf caractères au maximum pour USD.

TRIALTAXAMT Montant de taxe par cycle de facturation pour chaque période d'essai.

BILLINGPERIOD Jeton horodaté dont la valeur a été renvoyée par la réponse

SetCustomerBillingAgreement . Nombre de caractères limite : 20 scaractères d'un octet. Valeurs autorisées : Jeton non expiré

Voir la description

Non

Oui

BILLINGFREQUENCY Le nombre de périodes de facturation constit uant un cycl e de

Oui

facturation.

REMARQUE : BILLINGFREQUENCY est ignoré si

BILLINGPERIOD est SemiMonth.

La combinaison de BillingPeriod et de BillingFrequency ne pouvant excéder une année, les valeurs maximales de BillingFrequency sont :

z Day: 365 z Week: 52 z SemiMonth: N/A z Mon th: 12 z Year: 1

98 Mai 2007Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

Liste de référence des méthodes et des champs de l'API NVP

Paiements récurrents

ABLEAU A.32 Requête CreateRecurringPaymentsProfile (suite)

Nom Description et type de données Obligatoire

TOTALBILLINGCYCLES Le nombre de cycles de facturation avant que la facturation standard ne

commence.

z Si aucune valeur n'est spécifiée ou si la valeur est 0, la période se

poursuit jusqu'à annulation ou désactivation des préférences.

z Si la valeur est supérieure à 0, la période finira au terme de la

période d'essai et se poursuivra à BillingFrequency pour TotalBillingCycles.

AMT Montant de la facturation pour chaque période.

SHIPPINGAMT Montant des frais de livraison pour chaque péri ode

TAXAMT Montant de taxe pour chaque période.

Non

Oui

Non

MAXFAILEDPAYMENTS Le nombre d'échecs de paiement autorisés avant que les préférences ne

Non

soient automatiquement annulées. Nombre de caractères limite : numéro de chaîne représentant un chiffre

entier

Réponse à CreateRecurringPaymentsProfile

ABLEAU A.33 Réponse à CreateRecurringPaymentsProfile

Champ Description

PROFILEID Un identifiant unique pour toute référence ultérieure aux détails de ce paiement

récurrent. Nombre de caractères limite : 20 caractères alphanumériques d'un octet

Guide de développement et référence de l’API Paire Nom-Valeur (NVP) Mai 2007 99

Liste de référence des méthodes et des champs de l'API NVP

Transactions de référence

DoReferenceTransaction

DoReferenceTransactionRequest

ABLEAU A.34 Champs de DoReferenceTransactionRequest

Nom NVP Type de données et description Obligatoire

REFERENCEID Créer une nouvelle transaction à partir de n'importe lequel des éléments

suivants :

PAYMENTACTION Mode d'obtention du paiement :

z A uthorization indique que ce paiement est une autorisation de

base qui sera traitée par

z S ale indique qu'il s'agit d'une vente finale pour laquelle vous

demandez un paiement.

IPADDRESS Adresse IP du navigateur du payeur.

IMPORTANT : PayPal enregistre cette adresse IP afin de détecter des

fraudes éventuelles.

Nombre de caractères limite : 15 caractères d'un octet, y compris les points, par exemple : 255.255.255.25.

EMAIL Adresse email du payeur.

Nombre de caractères limite : 127 caractères d'un octet.

PAYERID Numéro de compte unique du client PayPal.

Nombre de caractères limite:13 caractères alphanumériques d'un octet.

FIRSTNAME Prénom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

Autorisation et collecte.

Oui

Non

Oui

LASTNAME Nom du payeur.

Nombre de caractères limite : 25 caractères d'un octet.

STREET Première adresse postale.

Nombre de caractères limite : 100 caractères d'un octet.

CITY Nom de la ville.

Nombre de caractères limite : 40 caractères d'un octet.

STATE Etat ou province.

Nombre de caractères limite : 40 caractères d'un octet. Pour une abréviations des états ou provinces, reportez-vous à l’

Oui

Non

«Abréviations des états ou provinces» page 57.

100 Mai 2007 Guide de développement et référence de l’API Paire Nom-Valeur (NVP)

PAYPAL NVP API - 2007, NVP API - 2012 User Manual [fr]

Specifications and Main Features

Frequently Asked Questions

User Manual

A propos de ce document

Public ciblé

Problèmes relatifs à la documentation

Historique des révisions

Présentation

Présentation de l'API NVP PayPal

Intégrer avec l'API PayPal

Etapes de base

Créer une application Web

Obtenir des informations d'authentification API

Transférer votre application dans l'environnement de production de PayPal

Créer et envoyer la requête

Interpréter la réponse

Créer un compte Business PayPal

Détails techniques

Créer des informations d'authentification API

Modifier votre code

Modèle de requête-réponse

Format de la requête

Format de la réponse

Envois utilisant HTTPS

Accepter PayPal dans la fonction Paiement express

Procédure de paiement de base via PayPal

1. Initialiser le paiement à l'aide de SetExpressCheckout

2. Rediriger le navigateur du client vers la page de connexion à PayPal

3. Récupérer les informations du client à l'aide de GetExpressCheckoutDetails

4. Effectuer une vente à l'aide de DoExpressCheckoutPayment

Vérifier l'adresse de livraison à l'aide de SetExpressCheckout

Exiger une adresse confirmée

Supprimer l'affichage de l'adresse de livraison sur PayPal

Ignorer l'adresse de livraison enregistrée auprès de PayPal

Changer la langue de la page de connexion à PayPal à l'aide de SetExpressCheckout

Sélectionner un style de pages de paiement prédéfini

Spécifier les paramètres du Logo et des couleurs individuellement

Remplir le formulaire de votre page de vérification de paiement à l'aide de GetExpressCheckoutDetails

Effectuer une vente à l'aide de DoExpressCheckoutPayment

Autoriser des collectes multiples à l'aide de SetExpressCheckout et de DoExpressCheckoutPayment

Inclure le détail des objets à l'aide de DoExpressCheckoutPay me n t

Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment

Mettre à jour les détails de la commande à l'aide de DoExpressChec ko utPayment

Comment utiliser l'API Paiements récurrents

Présentation

Limites

Créer un paiement récurrent

Procédure de création des paiements récurrents

Lancer la procédure à l'aide de SetCustomerBillingAgreement

Spécifier un style de page de paiement personnalisé

Personnaliser le logo et les couleurs

Rediriger le navigateur du client vers PayPal

Obtenir les informations du payeur à l'aide de GetBillingAgreementCustomerDetails

Effectuer la transaction à l'aide de CreateRecurringPaymentsProfile

Récapitulatif des Préférences de paiements récurrents

Fonctions de gestion

Effectuer plusieurs collectes partielles dans une commande à l'aide de DoCapture

Insérer un numéro de facture et une remarque lors de la collecte à l'aide de DoCapture

Effectuer un remboursement à l'aide de RefundTransaction

Rechercher une transaction à l'aide de TransactionSearch

Remboursement intégral

Remboursements partiels

Insérer une remarque lors du remboursement

Visualiser les détails d'une seule transaction à l'aide de GetTransactionDetails

Caractéristiques générales des requêtes et des paramètres

Paramètres

Champs multi-valeurs

Devises acceptées par PayPal

Paiement express PayPal

Requête SetExpressCheckout

Réponse SetExpressCheckout

Requête GetExpressCheckoutDetails

Réponse GetExpressCheckoutDetails

Requête DoExpressCheckoutPayment

Réponse DoExpressCheckoutPayment

Autorisation et collecte

DoAuthorization

DoCapture

DoReauthorization