PAYPAL NVP API - 2008 User Manual [fr]

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

Dernière mise à jour : Janvier 2008

Guide de développement et référence de l’API NVP PayPal

Référence : 100018.fr_FR-200801

© 2008 PayPal, Inc. Tous droits réservés. PayPal est une marque déposée de PayPal, Inc. Le logo PayPal est une marque de PayPal, Inc. Les autres marques et marques commerciales déposé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 S.à.r.l. & Cie, S.C.A. est soumise par la Commission de Surveillance du Secteur Financier du Luxembourg à la réglementation des établissements bancaires. Numéro d'enregistrement de PayPal au RCS : 118349

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.

Table des matières

Préface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

A propos de ce document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Public ciblé. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Historique des révisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapitre 1 Présentation . . . . . . . . . . . . . . . . . . . . . . . . .11

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

Intégrer votre application avec l'API PayPal. . . . . . . . . . . . . . . . . . . . . . . 11

Etapes de base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Créer une application Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

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

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

Interpréter la réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

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

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

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

Modifier votre code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Détails techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

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

Format de la requête. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Format de la réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Envois utilisant HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

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

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

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

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

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

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

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

Exiger une adresse confirmée. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

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

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

Guide de développement et référence de l’API NVP Janvier 2008 3

Table des matières

Changer la langue de la page de connexion à PayPal . . . . . . . . . . . . . . . . . . . 26

Modifier le Logo des pages PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Choix d'un style de page de paiement personnalisé. . . . . . . . . . . . . . . . . . . 26

Personnaliser le logo et les couleurs individuellement . . . . . . . . . . . . . . . . . 27

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

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

Autoriser une collecte unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Autoriser les collectes multiples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

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

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

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

Mettre à jour les détails de la transaction avec DoExpressCheckoutPayment . . . . . . . 32

Mettre à jour l'adresse de livraison avec DoExpressCheckoutPayment. . . . . . . . . . . 33

Paiement express PayPal pour les enchères eBay . . . . . . . . . . . . . . . . . . . . . 33

Chapitre 3 API Paiements récurrents . . . . . . . . . . . . . . . . . .35

Chapitre 4 Fonctions de gestion . . . . . . . . . . . . . . . . . . . .37

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

Effectuer une collecte unique avec DoCapture . . . . . . . . . . . . . . . . . . . . . . . 37

Effectuer plusieurs collectes partielles avec DoCapture . . . . . . . . . . . . . . . . . . . 38

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

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

Remboursement intégral. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Remboursements partiels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Insérer une remarque lors du rembours ement . . . . . . . . . . . . . . . . . . . . . 40

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

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

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

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

Paramètres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Champs multi-valeurs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Devises acceptées par PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Paiement express PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Requête SetExpressCheckout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Réponse SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4 Janvier 2008 Guide de développement et référence de l’API NVP

Table des matières

Requête GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Réponse GetExpressCheckoutDetails. . . . . . . . . . . . . . . . . . . . . . . . . . 51

Requête DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . 52

Réponse DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . 57

Autorisation et collecte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

DoReauthorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

DoVoid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

RefundTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

TransactionSearch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Paiement groupé. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Requête MassPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Réponse MassPay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Paiements récurrents et transactions de référence . . . . . . . . . . . . . . . . . . . . . 79

CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

GetRecurringPaymentsProfileDetails . . . . . . . . . . . . . . . . . . . . . . . . . . 87

ManageRecurringPaymentsProfileStatus . . . . . . . . . . . . . . . . . . . . . . . . 91

BillOutstandingAmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

UpdateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

SetCustomerBillingAgreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . . . . . . . .100

DoReferenceTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

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

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

Erreurs de validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

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

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

Messages d'erreur de l'API Autorisation et collecte . . . . . . . . . . . . . . . . . . . . .135

Erreurs de l'API RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Erreurs de l'API TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Erreurs de l'API GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Erreurs de l'API MassPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Erreurs d'API des paiements récurrents etdes transactions de référence . . . . . . . . .150

Erreurs de paiements récurrents . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Erreurs de SetCustomerBillingAgreement. . . . . . . . . . . . . . . . . . . . . . . .157

Guide de développement et référence de l’API NVP Janvier 2008 5

Table des matières

Erreurs de GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . .159

Erreurs de DoReferenceTransaction . . . . . . . . . . . . . . . . . . . . . . . . . .159

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

Descriptions des exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

Accepter PayPal dans la fonction Paiement express . . . . . . . . . . . . . . . . . .167

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

Fichiers communs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170

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

Exemples utilisant ASP classique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

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

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Exemples utilisant PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

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

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Exemples utilisant ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Logiciel requis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

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

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Annexe D Kit de développement PayPal Java . . . . . . . . . . . . 175

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

Normes prises en charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

Configuration matérielle recommandée . . . . . . . . . . . . . . . . . . . . . . . . .175

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

Configuration post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176

Documentation complète du kit de développement PayPal etdes classes d'API . . . . . .177

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

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178

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

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180

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

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

6 Janvier 2008 Guide de développement et référence de l’API NVP

Table des matières

Annexe E Kit de développement PayPal ASP.NET . . . . . . . . . . 183

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

Normes prises en charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Télécharger et installer le kit de développement PayPal . . . . . . . . . . . . . . . .184

Configuration post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184

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

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

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

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

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

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188

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

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

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

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

Installer les exemples sur Microsoft IIS . . . . . . . . . . . . . . . . . . . . . . . . . . .191

Exécuter les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192

Annexe F Kit de développement PayPal Ruby on Rails . . . . . . . 193

Installation du kit de développement PayPal Ruby on Rails. . . . . . . . . . . . . . . . .193

Normes prises en charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Configuration matérielle recommandée . . . . . . . . . . . . . . . . . . . . . . . . .194

Installation du kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . .194

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

Prise en charge d'un serveur proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195

Annexe G Codes pays . . . . . . . . . . . . . . . . . . . . . . . . 197

Guide de développement et référence de l’API NVP Janvier 2008 7

Table des matières

8 Janvier 2008 Guide de développement et référence de l’API NVP

Préface

A propos de ce document

Le Guide de développement et référence de l’API NVP décrit l'API Paire Nom-Valeur de PayPal.

Public ciblé

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

Historique des révisions

Historique des révisions du Guide de développement et référence de l’API NVP.

TABLEAU P.1 Historique des révisions

Date Description

Janvier 2008

Septembre 2007

Août 2007 Ajout de certains concepts liés aux paiements récurrents, modification de

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

z Ajout de champs d'autorisation de facturation à SetExpressCheckout pour les

paiements récurrents;

z Mise à jour de CreateRecurringPaymentsProfile avec de nouvelles fonctions

de paiements récurrents;

z Ajout de nouvelles API pour les paiements récurrents; z Ajout de l'API DoNonReferencedCredit.

z Mise à jour des enchères eBay dans la section Paiement express; z Ajout de champs destinés au mode de paiement giropay dans les API de

Paiement express.

SetExpressCheckout, de DoExpressCheckoutPayment et de DoReferenceTransaction, et ajout de codes d'erreur pour DoReferenceTransaction.

SetCustomerBillingAgreement, GetBillingAgreementCustomerDetails et CreateRecurringPaymentsProfile.

Guide de développement et référence de l’API NVP Janvier 2008 9

Historique des révisions

ABLEAU P.1 Historique des révisions

Date Description

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

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

l’API de Paiement express, avec l'ajout de SHIPTOCOUNTRYCODE.

10 Janvier 2008 Guide de développement et référence de l’API 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 aux fonctionnalités commerciales de PayPal permettant 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 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 Connaître les détails d'une transaction spécifique.

Il est facile d’intégrer PayPal à votre application Web 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 votre application avec l'API PayPal

Vous pouvez utiliser l'API NVP PayPal par l'une ou l'autre des deux approches suivantes :

Intégrer directement

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 exemples téléchargeables vous montrent comment intégrer directement en utilisant ASP classique, PHP et ColdFusion.

Guide de développement et référence de l’API NVP Janvier 2008 11

Présentation

Etapes de base

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,

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

Exemples

Pour vous aider à utiliser l'API NVP PayPal, des exemples sont fournis à l'adresse

http:/www.paypal.fr/fr_FR/html/Espace-Integration-PayPal/ic_nvp.html. Grâce ces exemples, vous

pouvez envoyer des appels d’API à l'Environnement de test de PayPal.

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 13, 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 consiste à télécharger et à tester les exemples

d'applications comme indiqué au paragraphe « Intégrer votre application avec

l'API PayPal » page 11.

Créer une application Web

Votre intégration 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 ci-après 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.

12 Janvier 2008 Guide de développement et référence de l’API NVP

Présentation

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

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

Identifiant API sdk-three_api1.sdk.com Mot de passe API QFZCWN5HZM8VBG7Q Signature API A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

Créer et envoyer la requête

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

1. Codez au format URL les paramètres noms et valeurs dans la requête pour que tous les

caractères soient transmis correctement. Cette action est décrite au paragraphe « Codage au format URL » page 15

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

« Format de la requête » page 16. Le format NVP est décrit à « Format NVP » page 15.

3. Envoyez ensuite la requête NVP à l'Environnement de test PayPal comme indiqué à la

section « Envois utilisant HTTPS » page 19.

Interpréter la réponse

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

1. Recevoir la réponse HTTP et procéder à l'extraction de la chaîne NVP;

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

section « Codage au format URL » page 15;

3. Prendre les mesures appropriées selon que les réponses contiennent un message de réussite

ou d'échec.

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.

Guide de développement et référence de l’API NVP Janvier 2008 13

Présentation

Détails techniques

Créer un compte Business PayPal

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

www.paypal.fr.

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

Pour savoir comment obtenir des informations d'authentification API pour votre compte Business, consultez la page https://www.paypal.com/IntegrationCenter/ic_certificate.html

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 doit

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

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

informations d'authentification API » page 14.

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.

14 Janvier 2008 Guide de développement et référence de l’API NVP

Présentation

Détails techniques

Format URL

La requête et la réponse sont encodées au format URL qui est définit 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

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.

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

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

FIRSTNAME=Robert

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

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Morel

z Dans une chaîne NVP, les valeurs de chaque champ sont codées au format URL.

Codage au format URL

La requête et la réponse sont codées au format URL. Ce format garantit la transmission des caractères spéciaux, qui ne sont pas autorisés dans une URL, ainsi que ceux dotés d’une signification particulière dans une URL tels que le signe égal et l'esperluette. Par exemple, la chaîne NVP suivante :

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

NAME=Robert Morel&COMPANY=R. Morel & Cie

est codée au format URL de la manière suivante :

NAME=Robert+Morel&COMPANY=R%2E+Morel+%26+Cie

Utilisez les méthodes suivantes pour convertir au/du format URL vos chaînes NVP :

TABLEAU 1.2 Méthodes de codage au format URL

Langage Méthode

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

Encoding.Default)

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

Encoding.Default)

ASP classique

Java Codage java.net.URLEncoder.encode

PHP Codage urlencode()

Codage Server.URLEncode

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

disponibles sur Internet.

Décodage java.net.URLDecoder.decode

Guide de développement et référence de l’API NVP Janvier 2008 15

Présentation

Détails techniques

ABLEAU 1.2 Méthodes de codage au format URL

Langage Méthode

Décodage urldecode()

ColdFusion Codage URLEncodedFormatstring [, charset ]

Décodage URLDecodeurlEncodedString[, charset])

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.

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

Paramètres de sécurité obligatoires

Paramètres de corps

USER=nomUtilisateurApi&PWD=motDePasseApi&SIGNATURE=signatureApi

&SUBJECT=adresseEmailTiersFacultative&VERSION=3.2

Les paramètres suivants sont toujours obligatoires :

USER

PWD

VERSION=3.2

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

exemples sous la forme suivante :

[parametresDeSecuriteObligatoires]

&METHOD=nomMethode&autresParametresObligatoiresEtFacultatifs

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 METHOD, vous pouvez spécifier les paramètres dans l'ordre de votre choix.

Paramètres de sécurité

Les paramètres de sécurité 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.

16 Janvier 2008 Guide de développement et référence de l’API NVP

Présentation

Détails techniques

ABLEAU 1.4 Paramètres de sécurité obligatoires : Informations d'authentification API

Paramètre Valeur

VERSION=

SIGNATURE Facultatif Votre chaîne de signature API PayPal.

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

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

Obligatoire Le numéro de version du service API NVP.

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

appel. Définissez ce paramètre seulement si vous appelez une API pour le

compte d'un autre utilisateur.

intégration. Nous vous conseillons de sauvegarder ces valeurs dans un endroit sûr autre que la racine des documents de votre serveur W eb. 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 doit 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 devez 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 METHOD. En outre, chaque méthode nécessite des paramètres obligatoires et facultatifs :

METHOD=nomDeLaMethode¶metresRequisEtFacultatifs

Toutes les méthodes d'API et leurs paramètres sont détaillé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, « Accepter PayPal dans la fonction Paiement express » et

Chapitre 4, « Fonctions de gestion ». D’autres exemples d'utilisation figurent au Chapitre 2, « Accepter PayPal dans la fonction Paiement express ».

Guide de développement et référence de l’API NVP Janvier 2008 17

Présentation

Détails techniques

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 général d'une réponse indiquant une ré ussite

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

Champs de la réponse API

Chaque réponse comprend le champ ACK. Si la valeur du champ est Success ou SuccessWithWarning, vous devez 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 champ BUILD compris. Les champs importants se trouvent 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 ». La façon d’utiliser les champs dépend 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 aux erreurs

Si la valeur du champ ACK est Error ou Warning, 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

ACK=Success&TIMESTAMP=date/heureDeReponse

&CORRELATIONID=jetonDebogage&VERSION=3.200000

&BUILD=numeroBuild

&NOM1=valeur1&NOM2=valeur2&NOM3=valeur3&...

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

[champsReponseReussie]

Champs de la réponse d'erreur

ACK=Error&TIMESTAMP=date/heureDeLaReponse&

CORRELATIONID=jetonDebogage&VERSION=2.300000&

BUILD=numeroBuild&L_ERRORCODE0=codeErreur&

L_SHORTMESSAGE0=messageCourt&

L_LONGMESSAGE0=messageLong&

L_SEVERITYCODE0=codeGravite

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 connaître 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érence des messages d'erreur ».

18 Janvier 2008 Guide de développement et référence de l’API NVP

Valeurs du paramètre ACK

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

TABLEAU 1.7 Valeurs du paramètre ACK

Type de réponse Valeur

Réponse de réussite Success

Réponse d'erreur Failure

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 en environnement de production et un autre en environnement de test permettant de tester les transactions.

Présentation

Détails techniques

SuccessWithWarning

FailureWithWarning

Warning

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/nvp Environnement de production : 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 Environnement de production : https://api.paypal.com/nvp

Guide de développement et référence de l’API NVP Janvier 2008 19

Présentation

Détails techniques

20 Janvier 2008 Guide de développement et référence de l’API 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 21 z « Vérifier l'adresse de livraison à l'aide de SetExpressCheckout » page 24 z « GetExpressCheckoutDetails renvoie l'adresse de livraison igno rée. » page 25 z « Modifier le Logo des pages PayPal » page 26 z « Remplir le formulaire de votre page de vérification de paiement » page 27 z « Effectuer une vente à l'aide de DoExpressCheckoutPayment » page 28 z « Autoriser une collecte unique » page 28 z « Autoriser les collectes multiples » page 29 z « Changer l'URL de la Notification instantanée de paiement (IPN) » page 30 z « Inclure le détail des objets à l'aide de DoExpressCheckoutPayment » page 30 z « Inclure les sous-totaux à l'aide de DoExpressCheckoutPayment » page 31 z « Mettre à jour les détails de la transaction avec DoExpressCheckoutPayment » page 32 z « Mettre à jour l'adresse de livraison avec DoExpressCheckoutPayment » page 33 z « Paiement express PayPal pour les enchères eBay » page 33

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.

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

Guide de développement et référence de l’API NVP Janvier 2008 21

Accepter PayPal dans la fonction Paiement express

Procédure de paiement de base via PayPal

La réponse SetExpressCheckout, vous fournit un jeton TOKEN qui identifie de manière unique cette transaction en trois étapes. Vous devez transmettre ce jeton TOKEN dans les requêtes GetExpressCheckoutDetails et DoExpressCheckoutPayment. GetExpressCheckoutDetails et DoExpressCheckoutPayment 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

TABLEAU 2.1 Initialiser le paiement

Requête

Réponse

[parametresDeSecuriteObligatoires]&METHOD=SetExpressCheckout&AMT=10.00&

RETURNURL=https://www.masociete.com/traitementcommandes/affichcommande.html& CANCELURL=https://www.unesociete.com/traitementcommande/infolivraison.html

[champsReponseReussite]&TOKEN=EC-3DJ78083ES565113B

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

PAYMENTACTION sera sa valeur par défaut : Sale.

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/cgi-bin/webscr?cmd=_express-checkout& token=valeur_retournee_par_SetExpressCheckoutResponse

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

22 Janvier 2008 Guide de développement et référence de l’API NVP

Accepter PayPal dans la fonction Paiement express

Procédure de paiement de base via PayPal

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 jeton TOKEN ainsi que les informations du client.

TABLEAU 2.2 Obtenir les informations du payeur

Requête

Réponse

[parametresDeSecuriteObligatoires]&METHOD=GetExpressCheckoutDetails&

TOKEN=EC-3DJ78083ES565113B

[champsReponseReussie]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@unemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=Claude& LASTNAME=Martin&COUNTRYCODE=FR& SHIPTONAME=Claude+Martin&SHIPTOSTREET=144+Grande+rue& SHIPTOCITY=Carpentras&SHIPTOSTATE=none&SHIPTOCOUNTRYCODE=FR& SHIPTOZIP=84200&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmed

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

Enregistrez 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 Paiement express PayPal de PayPal à l'aide 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 les collectes multiples » page 29.

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. PAYMENTACTION: choisissez Sale. Il s'agit de la valeur par défaut de SetExpressCheckout. AMT: utilisez la même valeur que pour la requête SetExpressCheckout

TABLEAU 2.3 Effectuer une vente

Requête

Guide de développement et référence de l’API NVP Janvier 2008 23

[parametresDeSecuriteObligatoires]&METHOD=DoExpressCheckoutPayment&

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

Accepter PayPal dans la fonction Paiement express

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

Réponse [champsReponseReussie]&TOKEN=EC-0E881823PA052770A&

TRANSACTIONID=8SC56973LM923823H&TRANSACTIONTYPE=expresscheck out& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T20:16:05Z&AMT=10.00& CURRENCYCODE=USD&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 ADDROVERRIDE de la requête SetExpressCheckout.

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

xxx.

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

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

[parametresDeSecuriteRequis]&METHOD=SetExpressCheckout&AMT=10.00&

RETURNURL=https://www.masociete.com/traitementcommandes/affichcommande.html& CANCELURL=https://www.unesociete.com/traitementcommande/infoslivraison.html &REQCONFIRMSHIPPING=1

[champsReponseReussie]&TOKEN=EC-0E881823PA052770A

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

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

ABLEAU 2.5 Supprimer l'adresse de livraison

Requête

Réponse

24 Janvier 2008 Guide de développement et référence de l’API NVP

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P

Accepter PayPal dans la fonction Paiement express

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

GetExpressCheckoutDetails ne renvoie pas l'adresse de livraison.

TABLEAU 2.6 GetExpressCheckoutDetails

Requête

Réponse

[parametresDeSecuriteObligatoires]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-17C76533PL706494P

[champsReponseReussie]&TOKEN=EC17C76533PL706494P&EMAIL=abcdef@unesociete.com&PAYERID=95HR9CM6D56Q2& PAYERSTATUS=verified&FIRSTNAME=Claude&LASTNAME=Martin&COUNTRYCODE=FR& ADDRESSID=PayPal&ADDRESSSTATUS=None

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ément ADDROVERRIDE la valeur 1 et définissez les champs de l'adresse de livraison (consultez le Tableau A.3, « 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

[parametresDeSecuriteObligatoires]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.masociete.com/traitementcommandes/affichcommande.html& CANCELURL=https://www.unesociete.com/traitementcommande/infoslivraison.html &SHIPTONAME=Claude+Martin&SHIPTOSTREET=144+grande+rue&SHIPTOCITY=CARPENTRAS &SHIPTOSTATE=none&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=84200&

ADDROVERRIDE=1

Réponse

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails renvoie l'adresse de livraison ignorée.

TABLEAU 2.8 GetExpressCheckoutDetails

Requête

Réponse

Guide de développement et référence de l’API NVP Janvier 2008 25

[parametresDeSecuriteObligatoires]&METHOD=GetExpressCheckoutDetails&TOKEN=EC- 17C76533PL706494P

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P& PAYER=abcdef@unesociete.com&PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified& FIRSTNAME=Claude&LASTNAME=Martin& COUNTRYCODE=FR&SHIPTONAME=Claude+Martin&SHIPTOSTREET=144+grande+rue& SHIPTOCITY=CARPENTRAS&SHIPTOSTATE=none&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=84200& ADDRESSID=PayPal&ADDRESSSTATUS=Unconfirmed

Accepter PayPal dans la fonction Paiement express

Changer la langue de la page de connexion à PayPal

Pour changer la langue de la page de connexion à PayPal, donnez à LOCALECODE une des valeurs autorisées dans SetExpressCheckout. Pour obtenir plus d'informations au sujet des valeurs de LOCALECODE, consultez le T ableau A.1, « Devises acceptées par PayPal et codes de

devises pour les transactions ». Dans l'exemple suivant 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

[parametresDeSecuriteObligatoires]&METHOD=SetExpressCheckout&AMT=10.00& CURRENCYCODE=EUR& RETURNURL=https://www.masociete.com/traitementcommandes/affichcommande.html& CANCELURL=https://www.unesociete.com/traitementcommandes/infoslivraison.html &LOCALECODE=fr_FR

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P

Modifier le Logo des pages PayPal

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.

Choix d'un style de page de paiement personnalisé

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 Choix d'un style de page de paiement person nalisé

Requête

Réponse

26 Janvier 2008 Guide de développement et référence de l’API NVP

PAGESTYLE=DesignerFotos-Yellow

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P

Accepter PayPal dans la fonction Paiement express

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

Personnaliser le logo et les couleurs individuellement

Pour que les pages Web 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 devant s'afficher en haut à gauche de la page de paiement. z HDRBORDERCOLOR : définit la couleur de bordure encadrant 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 Personnaliser le logo et les couleurs individuellement

Requête

Réponse

HDRIMG=https://www.masociete.com/images/ImageEnTete.gif& HDRBORDERCOLOR=3366FF&HDRBACKCOLOR=D3EFF5&PAYFLOWCOLOR=F8F5F5

[champsReponseReussie]&TOKEN=EC-17C76533PL706494P

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

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

[parametresDeSecuriteObligatoires]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-3DJ78083ES565113B

[champsReponseReussie]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@unemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=Claude&LASTNAME=Martin& COUNTRYCODE=FR&SHIPTONAME=Claude+Martin&SHIPTOSTREET=144+grande+rue& SHIPTOCITY=CARPENTRAS&SHIPTOSTATE=none&SHIPTOCOUNTRYCODE=FR&SHIPTOZIP=84200& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed

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

z SALUTATION

z FIRSTNAME

z MIDDLENAME z LASTNAME

Guide de développement et référence de l’API NVP Janvier 2008 27

Accepter PayPal dans la fonction Paiement express

Effectuer une vente à l'aide de DoExpressCheckoutPayment

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

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

Autoriser une collecte unique

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

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

[parametresDeSecuriteObligatoires]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.masociete.com/traitement_commandes/affich_commande.html& CANCELURL=https://www.masociete.com/traitement_commandes/infoslivraison.html&

PAYMENTACTION=Authorization

[champsReponseReussie]& TOKEN=EC-30P862430W113011F

Requête

[parametresDeSecuriteObligatoires]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-30P862430W113011F&PAYERID=95HR9CM6D56Q2&AMT=10.00

PAYMENTACTION=Authorization

28 Janvier 2008 Guide de développement et référence de l’API NVP

Accepter PayPal dans la fonction Paiement express

Autoriser les collectes multiples

Réponse

[champsReponseReussie]&TOKEN=EC-30P862430W113011F& TRANSACTIONID=4D479374VP578364Y&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:02:42Z&AMT=10.00& CURRENCYCODE=USD&TAXAMT=0.00&PAYMENTSTATUS=Pending& PENDINGREASON=authorization&REASONCODE=None

Le réglage de PAYMENTACTION sur Order vérifie que le compte du client existe, mais ne bloque pas les fonds. Pour autoriser les fonds, vous devez également appeler l'API

DoAuthorization en indiquant le montant à autoriser . Dans la plupart des cas, vous appelez DoAuthorization directement après DoExpressCheckout dans votre flux de paiement

afin de réduire les risques de rejet de la collecte. Utilisez la valeur de la variable TRANSACTIONID de la réponse

DoExpressCheckoutPayment comme valeur de TRANSACTIONID dans la requête DoAuthorization. Utilisez ensuite celle de AUTHORIZATIONID contenue dans la réponse DoAuthorization pour la requête DoCapture pour effectuer la collecte sur la commande.

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

unique avec DoCapture » page 37.

Autoriser les collectes multiples

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

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

PAYMENTACTION=Order

[champsReponseReussie]&TOKEN=EC-8NB10343BA3562027

[parametresDeSecuriteObligatoires]&METHOD=DoExpressCheckoutPayment&

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

PAYMENTACTION=Order

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

REASONCODE=None

Guide de développement et référence de l’API NVP Janvier 2008 29

Accepter PayPal dans la fonction Paiement express

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

Avant d'effectuer une collecte sur la commande, vous deve z commencer par appeler

DoAuthorization pour autoriser le montant de la transaction. Utilisez la valeur de TRANSACTIONID de DoExpressCheckoutPayment comme valeur de TRANSACTIONID dans la requête DoAuthorization. Dans la plupart des cas, vous devez appeler DoAuthorization directement après DoExpressCheckout dans votre flux de paiement.

Utilisez la valeur de AUTHORIZATIONID contenue dans la réponse DoAuthorization dans la requête DoCapture pour effectuer la collecte sur la commande. Pour en savoir plus sur la fonction Autorisation et collecte, consultez « Effectuer plusieurs collectes partielles avec

DoCapture » page 38.

Pour en savoir plus sur DoCapture, reportez-vous à la section « Collecter, Autoriser , Annuler

et Demander une nouvelle autorisation » page 37.

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

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 du marchand qui est utilisée, s'il en existe une.

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

[parametresDeSecuriteObligatoires]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00& PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/

[champsReponseReussie]&TOKEN=EC-8AX1275942659774U& TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=USD&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é

30 Janvier 2008 Guide de développement et référence de l’API NVP

+ 177 hidden pages