PAYPAL API Soap - 2007 Guide de référence [fr]

Guide de référence de l'API SOAP Référence : 100002.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.

Sommaire

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

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

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

Conventions typographiques. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

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

Historique des révisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapitre 1 Architecture de l'API SOAP de PayPal . . . . . . . . . . . 13

Architecture des services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Définitions du schéma WSDL/XSD PayPal . . . . . . . . . . . . . . . . . . . . . . . 14

Concepts et terminologie API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Sécurité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

RequesterCredentials SOAP : identifiant, mot de passe, signature et appelé. . . . . . 16

Nœuds de service SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Implémentation SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Style de message SOAP : doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Structure d'une requête SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Structure d'une requête . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Structure de la réponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Réponses aux erreurs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CorrelationID pour signaler des problèmes à PayPal . . . . . . . . . . . . . . . . . . 23

Définitions de l'API SOAP de PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Codage de caractères, types et formats des données et devises. . . . . . . . . . . . 24

API par fonction de gestion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

API pour échanger des fonds ou afficher des informations . . . . . . . . . . . . . . . 26

Notification instantanée de paiement et API. . . . . . . . . . . . . . . . . . . . . . . 26

Mai 2007 3

Sommaire

Chapitre 2 Structures fondamentales des requêtes

et des réponses eBL . . . . . . . . . . . . . . . . . . . . 29

Schéma des principaux types eBL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

AbstractRequestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

AbstractResponseType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapitre 3 API Autorisation et collecte . . . . . . . . . . . . . . . . .33

DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Schéma des types de DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

DoCaptureRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

DoCaptureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Schéma des types de DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . 41

DoAuthorizationRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

DoAuthorizationResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Schéma des types de DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

DoVoidRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

DoVoidResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

DoReauthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Schéma des types de DoReauthorization . . . . . . . . . . . . . . . . . . . . . . . . 45

DoReauthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

DoReauthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapitre 4 API Paiement express PayPal . . . . . . . . . . . . . . . 47

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

SetExpressCheckout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Schéma des types de Set ExpressCheckout . . . . . . . . . . . . . . . . . . . . . . 48

SetExpressCheckoutRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

SetExpressCheckoutResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Schéma des types de GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . 58

GetExpressCheckoutDetailsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 59

GetExpressCheckoutDetailsResponse . . . . . . . . . . . . . . . . . . . . . . . . . 60

DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Schéma des types de DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . 63

4 Mai 2007

Sommaire

DoExpressCheckoutPaymentRequest. . . . . . . . . . . . . . . . . . . . . . . . . . 64

DoExpressCheckoutPaymentResponse. . . . . . . . . . . . . . . . . . . . . . . . . 72

Chapitre 5 API GetTransactionDetails . . . . . . . . . . . . . . . . .77

Schéma des types de GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . 77

GetTransactionDetailsRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

GetTransactionDetailsResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapitre 6 API MassPay . . . . . . . . . . . . . . . . . . . . . . . .91

Notification instantanée de paiement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Schéma des types de MassPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

MassPayRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

MassPayResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Chapitre 7 API RefundTransaction . . . . . . . . . . . . . . . . . . . 97

Schéma des types de RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . 97

RefundTransactionRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

RefundTransactionResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Chapitre 8 API TransactionSearch . . . . . . . . . . . . . . . . . . 101

Schéma des types de TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . .101

TransactionSearchRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

TransactionSearchResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Champs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

Mai 2007 5

Sommaire

Chapitre 9 API Paiements récurrents . . . . . . . . . . . . . . . . . 109

SetCustomerBillingAgreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110

Schéma des types de SetCustomerBillingAgreement. . . . . . . . . . . . . . . . . .110

SetCustomerBillingAgreementRequest . . . . . . . . . . . . . . . . . . . . . . . . .110

SetCustomerBillingAgreementResponse . . . . . . . . . . . . . . . . . . . . . . . .113

GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

Schéma des types de GetBillingAgreementCustomerDetails . . . . . . . . . . . . . .114

GetBillingAgreementCustomerDetailsRequest . . . . . . . . . . . . . . . . . . . . .114

GetBillingAgreementCustomerDetailsResponse . . . . . . . . . . . . . . . . . . . .115

CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Schéma des types de CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . .115

CreateRecurringPaymentsProfileRequest. . . . . . . . . . . . . . . . . . . . . . . .116

CreateRecurringPaymentsProfileResponse. . . . . . . . . . . . . . . . . . . . . . .119

Chapitre 10 ReferenceTransactions . . . . . . . . . . . . . . . . . . 121

DoReferenceTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

DoReferenceTransactionRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

DoReferenceTransactionResponse . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Annexe A Codes et messages d'erreur de toutes les API PayPal . . 129

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

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

Erreurs de l'API GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Erreurs de l'API MassPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Erreurs de l'API RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

Erreurs de l'API TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

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

Erreurs SetCustomerBillingAgreement . . . . . . . . . . . . . . . . . . . . . . . . .160

Erreurs de GetBillingAgreementCustomerDetails . . . . . . . . . . . . . . . . . . . .162

Erreurs de CreateRecurringPaymentsProfile . . . . . . . . . . . . . . . . . . . . . .163

Transactions de référence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165

Annexe B Kit de développement Java pour l'API SOAP . . . . . . . 171

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

Langues acceptées . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Numéro de version du kit de développement PayPal . . . . . . . . . . . . . . . . . .171

Configuration matérielle recommandée . . . . . . . . . . . . . . . . . . . . . . . . . . .172

6 Mai 2007

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

Configuration post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Ajouter des fichiers JAR du kit de développement PayPal dans CLASSPATH . . . . .172

Répertoires et configurations facultatives du kit de développement PayPal . . . . . .173

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

Services d'API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177

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

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

Configurer ColdFusion pour le kit de développement PayPal Java . . . . . . . . . . . . .178

Récapitulatif des étapes de l'installation. . . . . . . . . . . . . . . . . . . . . . . . .178

Exemples de pages CFM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179

Recopier les fichiers JAR après les mises à jour WSDL . . . . . . . . . . . . . . . .180

Annexe C Kits de développement PayPal ASP.NET

et Classic ASP pour l'API SOAP . . . . . . . . . . . . . . . . . 181

Sommaire

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

Normes acceptées. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

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

Répertoires du kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . .182

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

Installer les exemples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Configuration du kit de développement PayPal . . . . . . . . . . . . . . . . . . . . . . .183

Ajouter les références ASP.NET dans les DLL du kit de développement PayPal . . . .183

Modifier le fichier Web.config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Définir le nombre maximum de tentatives pour les requêtes SOAP. . . . . . . . . . .184

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

Activer la prise en charge des procurations pour ASP.NET . . . . . . . . . . . . . . .186

Services d'API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186

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

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187

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

Classes COM spécifiques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

COMAdapter2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

COMArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

COMUtil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191

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

Mai 2007 7

Sommaire

Exemple d'utilisateur et de certificat d'API. . . . . . . . . . . . . . . . . . . . . . . .192

Installer les exemples sur Microsoft IIS . . . . . . . . . . . . . . . . . . . . . . . . .192

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Annexe D Kit de développement PHP pour l'API SOAP . . . . . . . 195

Configurer PHP et Apache pour le kit de développement PayPal . . . . . . . . . . . . . .195

Normes acceptées . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196

Langues acceptées . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196

Numéro de version du kit de développement PayPal . . . . . . . . . . . . . . . . . .196

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

Installer sur un ordinateur local . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197

Installer sur un ordinateur distant à partir de Microsoft Windows . . . . . . . . . . . .197

Répertoires et fichiers de configuration du kit de développement PayPal . . . . . . . . . .198

Fichier de configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199

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

Services d'API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200

Préférences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201

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

Exemples d'applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202

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

Exemple d'utilisateur et de certificat d'API. . . . . . . . . . . . . . . . . . . . . . . .203

Exécuter les exemples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203

Annexe E Abréviations des états et provinces. . . . . . . . . . . . 205

Annexe F Codes pays . . . . . . . . . . . . . . . . . . . . . . . . 209

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

8 Mai 2007

Préface

A propos de ce document

Ce document décrit l'API (Application Programming Interface) et le service SOAP PayPal.

Public ciblé

Ce document s'adresse aux programmeurs qui maîtrisent les normes de programmation, par exemple le protocole SOAP (Simple Object Access Protocol), le langage WSDL (Web Services Description Language) et le langage XSD (XML Schema Definition).

Conventions typographiques

Différents types de caractères sont utilisés dans ce document pour identifier les caractéristiques du texte. Ces types de caractères et leurs caractéristiques sont décrits cidessous :

Type de caractère Utilisation

italique sérif Titre de document

Terme traité ou défini Exemple : un fichier est un flux de données sous fo rm e de caractères lisibles ou

inscriptibles… Valeurs booléennes (pas les mots-clés)

Exemple : la fonction renvoie la valeur true si une erreur se produit.

Guide de référence de l'API SOAP Mai 2007 9

Conventions typographiques

Type de caractère Utilisation

police à espacement constant

gras sérif Noms d'interfaces utilisateur, tels que les noms de fenêtres ou les options de

oblique sansérif

Chemins d'accès aux fichiers ou noms de fichier apparaissant dans le corps du texte.

Noms associés au code apparaissant dans le corps du texte. Ces noms sont utilisés pour les fonctions, les rappels, les arguments, les structures de données et les champs.

Exemple : AbstractResponseType est le type de réponse SOAP sur lequel sont basés tous les modes de réponse API de PayPal.

Composants de requêtes et de réponses de protocole Internet, tels que les variables HTTPS et FORM.

Exemple : le système PayPal utilise une requête method=POST pour renvoyer les variables d'état NIP relatives aux abonnements, telles que txn_type.

menus. Exemple : dans la page Préférences, cliquez sur Email pour confirmer votre

adresse email. Espaces réservés utilisés dans le contexte d'un format, ou norme de

programmation, ou descriptions formelles de la syntaxe du système PayPal. Les espaces réservés indiquent les valeurs ou les noms que l'utilisateur doit fournir.

Exemple : par exemple, amount est la variable d'un panier contenant un seul objet, mais amount_X est le nom de la variable d'un panier contenant plusieurs objets. amount_3 est le montant du troisième objet dans un panier contenant plusieurs objets.

Outre les types de caractères décrits ci-dessus, les mots et les phrases de ce document peuvent également apparaître en gras ou soulignés, auquel cas ils donnent des informations supplémentaires. Ces informations sont décrites ci-dessous :

Attribut du texte Utilisation

xxxxxx Lien hypertexte vers une page du document actuel ou vers un autre document de

l'ensemble.

xxxxxx Lien hypertexte vers une URL ou démarrant une action Web, telle que l'envoi d'un

email.

10 Mai 2007 Guide de référence de l'API SOAP

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, sa date (indiquée dans le pied de page de chaque page) 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 :

1. Connectez-vous à votre compte à l'adresse https://developer.paypal.com/ en

entrant votre adresse email et votre mot de passe dans la zone Connexion sécurisée.

2. Cliquez sur Help Center en haut à droite de la page.

3. Cliquez sur Email PayPal Technical Support.

4. Complétez le formulaire.

Historique des révisions

Problèmes relatifs à la documentation

Historique des révisions du Guide de référence de l’API SOAP.

TABLEAU P.1 Historique des ré visions

Date Description

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

SetCustomerBillingAgreement, GetBillingAgreementCustomerDeta ils et CreateRecurringPaymentsProfile.

Mars 2007 Correction de problèmes mineurs y compris l'ajout des codes Switch/Solo aux

codes de réponse AVS et aux codes de réponse CVV2 (cryptogramme visuel),

dans le chapitre API Paiement direct. Février 2007 Correction de problèmes mineurs. Décembre 2006 Correction de problèmes mineurs. Octobre 2006 Ouvrage rebaptisé Guide de référence de développement d'API SOAP Les

guides précédents portant sur les kits de développement pour SOAP sont inclus

dans cet ouvrage. Juin 2006 Champ CardNumber ajouté à l'API TransactionSearch. Messages d'erreur

sensiblement améliorés pour l'API Paiement direct. Changements mineurs dans

un message d'erreur de l'API Paiements groupés. Mars 2006 Mise à jour avec les nouvelles informations d'identification des API : signatures

API. Nouveau nœud de service SOAP pour les signatures.

Diverses corrections mineures.

Guide de référence de l'API SOAP Mai 2007 11

Historique des révisions

ABLEAU P.1 Historique des ré visions (s uite)

Date Description

Janvier 2006 Messages d'erreur supplémentaires pour les API Autorisation et collecte et les

Décembre 2005 Suppression de la description erronée indiquant que le champ cpp-header-

API Paiement express PayPal.

image de SetExpressCheckoutRequest doit être encodé dans l'URL.

12 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de

PayPal

L'API SOAP de PayPal offre un accès par programmation aux fonctions et services de PayPal. Les développeurs peuvent créer des applications, des outils et des services personnalisés qui correspondent aux mêmes services et outils disponibles sur le site principal de Paypal, https://www.paypal.fr/. Les applications classiques sont la recherche de transactions, les paiements groupés et les remboursements. L'API repose sur des normes ouvertes communément appelées « Services Web », qui englobent le protocole SOAP (Simple Object Access Protocol), le langage WSDL (Web Services Definition Language) et le langage XSD (XML Schema Definition). Ces normes sont acceptées par un large éventail d'outils de développement sur diverses plates-formes.

Architecture des services

A l'instar de nombreux services Web, les services SOAP de PayPal constituent une combinaison de schémas, de serveurs matériels et logiciels et de services de base côté client et côté serveur.

Guide de référence de l'API SOAP Mai 2007 13

Architecture de l'API SOAP de PayPal

Architecture des services

FIGURE 1.1 Schéma détaillé des services SOAP de PayPal

Dans un modèle de traitement orienté objet, l'interface des requêtes et des répo nses SOAP est un objet dans le langage de programmation natif de votre application. Votre client SOAP tiers génère les interfaces vers des objets métier et les relais réseau à partir des fichiers WSDL et XSD fournis par PayPal qui indiquent la structure du message SOAP, son contenu et les liaisons des services de l'API PayPal. Une application d'entreprise utilise des données sous forme de propriétés d'objets pour envoyer et recevoir des données en appelant des méthodes d'objet. Le client SOAP gère les détails relatifs à la création de la requête SOAP, à son envoi au service PayPal et à la reconversion de la réponse en objet.

Définitions du schéma WSDL/XSD PayPal

Le schéma des services Web de PayPal et ses composants eBay Business Language (eBL) de base et principaux sous-jacents sont obligatoires pour développer des applications avec l'API PayPal. Le tableau ci-après indique les emplacements des fichiers WSDL et XSD.

TABLEAU 1.1 Emplaceme nts des fichiers WSDL e t XSD de PayPal

Développer et tester avec le service de l'API de l'Environnement de test de PayPal Schéma de PayPal https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl Composants eBL

de base et types de composants

https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd

14 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de PayPal

Architecture des services

ABLEAU 1.1 Emplace ments des fichiers WSDL e t XSD de PayPal ( suite)

Production avec le service de l'API PayPal en direct Schéma de PayPal https://www.paypal.com/wsdl/PayPalSvc.wsdl Composants eBL

de base et types de composants

http://www.paypal.com/wsdl/eBLBaseComponents.xsd http://www.paypal.com/wsdl/CoreComponentTypes.xsd

Concepts et terminologie API

Vous trouverez ci-dessous quelques concepts et termes de base concernant le service API de PayPal et l'authentification de la sécurité.

TABLEAU 1.2 Concepts et termes de b ase rela tifs à la configuration de l'API PayPal

Terme Définition

Appels API Services d'API (Application Programming Interface) PayPal permettant aux sociétés d'effectuer

des paiements, de rechercher des transactions, de rembourser des paiements, d'afficher les informations sur les transactions et d'autres fonctions de gestion.

Certificat d'API

Signature API S'exclut mutuellement avec la signature API. Signature numérique unique générée par PayPal

S'exclut mutuellement avec la signature API. Fichier de certificat numérique unique généré par PayPal que vous devez télécharger sur le site de PayPal et utiliser sur l'ordinateur client pour crypter les requêtes HTTPS de vos appels API vers le serveur API PayPal.

Vous pouvez utiliser un certificat d'API si vous disposez d'un contrôle total sur votre propre serveur Web.

(ligne de texte ou hachage) que vous copiez sur le site de PayPal et incluez dans vos appels API. Alternative à la sécurité par certificat d'API.

La combinaison de votre signature numérique, votre identifiant API et votre mot de passe API forme une authentification à trois jetons car vous incluez chacun d'eux comme jeton par programmation dans vos appels API.

Une signature API convient parfaitement pour les serveurs Web Microsoft Windows ou d'autres configurations de serveur Web partagées, par exemple celles utilisées par les services d'hébergement Web.

Identifiant et mot de passe API

Autorisation d'appelé

Guide de référence de l'API SOAP Mai 2007 15

Nom et mot de passe d'identification de compte générés par PayPal que vous utilisez spécifiquement pour effectuer des appels API. Vous devez entrer votre identifiant et votre mot de passe API pour chaque appel API. L'identifiant et le mot de passe API diffèrent de vos identifiant (adresse email) et mot de passe de connexion PayPal.

Indicateur dans un appel API du compte pour lequel l'appel est effectué. Correspond à la fonction par programmation de l'autorisation tierce. La valeur du champ Appelé est l'adresse email PayPal du tiers.

Architecture de l'API SOAP de PayPal

Architecture des services

ABLEAU 1.2 Concep ts et termes de base relatifs à la configuration de l'API PayPal

(suite)

Terme Définition

Accès direct Une société effectue elle-même des appels API à partir de son propre serveur vers le serveur de

PayPal. Elle possède son propre certificat d'API, ou encore sa signature, son identifiant et son mot de passe API.

Exemple : Un programmateur de la société d'un marchand obtient un fichier de certificat d'API délivré par

PayPal et effectue des appels API pour la société à partir de son serveur Web.

Accès tiers Une autre personne ou société effectue des appe ls API pour votre compte. Vous octroyez au tiers

la permission d'effectuer des appels API pour vous. Exemple : Un service d'hébergement sur Internet possède ses propres certificat d'API, identifiant et mot de

passe API. Ses clients, à savoir des marchands qui utilisent PayPal, autorisent le service d'hébergement à effectuer des appels API pour leur compte. Le service d'hébergement inclut l'adresse email PayPal du marchand dans le champ Appelé d'un appel API.

Sécurité

Le service API SOAP de PayPal est protégé, et seuls les membres PayPal autorisés peuvent l'utiliser. Il existe quatre niveaux de sécurité :

1. Un identifiant API (champ Identifiant) et un mot de passe API (champ Mot de passe)

obligatoires

2. Un troisième mécanisme d'authentification obligatoire, parmi les suivants :

– Signature des requêtes côté client via un certificat d'API émis par PayPal – Authentification des requêtes via une signature API incluse dans la requête (champ

Signature)

3. Autorisation tierce facultative d'effectuer l'appel API au nom d'un autre compte (champ

Appelé facultatif)

4. Transmission de données SSL (Secure Sockets Layer) En cas d'échec de la sécurité authentifiée à l'un de ces niveaux, l'accès à l'API SOAP de PayPal

est refusé.

RequesterCredentials SOAP : identifiant, mot de passe, signature et

appelé

Pour la sécurité de votre entreprise, PayPal doit vérifier que les marchands ou les développeurs tiers sont autorisés à initier une transaction avant d'en effectuer une. PayPal authentifie chaque requête. Si la requête ne peut pas être authentifiée, une erreur de sécurité SOAP est renvoyée.

16 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de PayPal

Architecture des services

Dans l'en-tête de la requête SOAP, votre client SOAP doit définir les éléments Username et Password pour transmettre une combinaison identifiant/mot de passe API. En outre, vous

pouvez définir les éléments Signature ou Subject pour indiquer votre chaîne de signature API et une adresse email de compte tiers facultative pour l'authentification. Vous trouverez cidessous un exemple partiel des éléments RequesterCredentials requis pour toutes les requêtes SOAP. Pour une corrélation de ces éléments avec la structure générique d'une requête SOAP complète, reportez-vous à la section « Structure d'une requête SOAP » page 18.

<SOAP-ENV:Header>

<RequesterCr edentials xmlns=”urn: ebay:api:PayPalAPI”

xsi:type=”ebl:CustomSecurityHe aderType”>

<Credentials xmlns=”urn:ebay:a pis:eBLBaseComponents ”

xsi:type=”ebl:UserIdPasswordTy pe”>

<Username >api_username</Username> <Password >api_password</Password> <Signature >api_signature</Signature> <Subject>authorizing_account_emailaddress</Subject>

</Credentials>

</RequesterCredentials>

</SOAP-ENV:Header>

où :

TABLEAU 1.3 Eléments d'auth entificat ion Reque sterCreden tials dan s un en-tête

SOAP

Elément Valeur Description

<Identifiant> api_username Votre identifiant API, généré automatiquement par PayPal

lorsque vous demandez un certificat numérique pour utiliser l'API SOAP de PayPal. Cette valeur s'affiche sur

https://www.paypal.fr/

> Informations relatives au certificat d'API.

REMARQUE : le Guide d'utilisation de l'Environnement de test

<Signature> api_signature Votre signature API, si vous en utilisez une à la place d'un

<Appelé> authorizing_

api_password Votre mot de passe API, que vous spécifiez lorsque vous

demandez un certificat numérique pour utiliser l'API SOAP de PayPal.

certificat d'API. Adresse email d'un tiers pour lequel vous envoyez des requêtes à

account_

emailaddress

l'API SOAP de PayPal. Votre identifiant API doit avoir reçu l'autorisation de ce tiers d'effectuer une requête API PayPal spécifique.

dans vos Préférences sous Accès à l'API

PayPal explique comment obtenir des

certificats numériques à utiliser avec l'API SOAP de PayPal.

Guide de référence de l'API SOAP Mai 2007 17

Architecture de l'API SOAP de PayPal

Nœuds de service SOAP

Selon le mécanisme d'authentification que vous avez choisi, vos requêtes SOAP doivent être traitées par différents nœuds de service.

TABLEAU 1.4 Nœuds de service SOAP

Mécanisme d'authentification Nœud de service réel de production

Signature API https://api-3t.paypal.com/2.0/ https://api-3t.sandbox.paypal.com/2.0/ Certificat d'API https://api.paypal.com/2.0/ https://api.sandbox.paypal.com/2.0/

REMARQUE : pour la correspondance entre les appels API et leurs nœuds de service,

Nœud de service test (Environnement de test)

reportez-vous au Tableau 1.8, « API par fonction de gestion », page 25.

Implémentation SOAP

Cette section contient des informations sur l'implémentation SOAP de PayPal.

Style de message SOAP : doc-literal

PayPal utilise des messages SOAP de type doc-literal, et non rpc-encoding. Avec doc-literal, un appel d'interface de service unique transmet un document XLM dans la

requête au serveur API de PayPal, qui répond par une instance de document XML.

Structure d'une requête SOAP

Le schéma suivant illustre le contenu de la structure d'une requête SOAP de PayPal. T outes les API PayPal reposent sur deux structures fondamentales : AbstractRequestType

et AbstractResponseType.

18 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de PayPal

FIGURE 1.2 Schéma de l'enveloppe d'une requête SOAP

Implémentation SOAP

Structure d'une requête

Vous trouverez ci-dessous la description annotée de la struct ure de requête SOAP requise par l'API SOAP de PayPal.

Structure générale de la requête SOAP de l'API PayPal

<?xml version=”1.0” encoding=” UTF-8”?> <SOAP-ENV:Envelope xmlns:xsi=” http://www.w3.org/ 2001/XMLSchema-instan ce”

xmlns:SOAP-ENC=”http://schemas .xmlsoap.org/soap/enc oding/” xmlns:SOAP-ENV=”http://schemas .xmlsoap.org/soap/env elope/” xmlns:xsd=”http://www.w3.org/2 001/XMLSchema” SOAP-ENV:encodingStyle=”http:/ /schemas.xmlsoap.o rg/soap/encoding/”

><SOAP-ENV:Header>

<Username >api_username</Username> <Password >api_password</Password> <Signature /> <Subject/>

</Credentials>

</RequesterCredentials>

</SOAP-ENV:Header> <SOAP-ENV:Body>

<specific_api_name_Req xmlns=”urn:ebay:api:PayP alAPI”>

Guide de référence de l'API SOAP Mai 2007 19

Architecture de l'API SOAP de PayPal

Implémentation SOAP

<specific_api_name_Request>

<Version xml ns=urn:ebay:apis:eBLBas eComponents”>service_version </Version> <required_or_optional_fields xsi:type=”some_type_here”> data </required_or_optional_fields>

</specific_api_name_Request>

</specific_api_name_Req>

</SOAP-ENV:Body> </SOAP-ENV:Envelope>

ABLEAU 1.5 Annotation d'une requête SOAP générique

Lignes Commentaire

12, 13 Les champs <Username> et <Password> font partie du mécanisme d'authentification

de la sécurité <RequesterCredentials> de l'API SOAP de PayPal que vous devez créer pour chaque en-tête de requête SOAP. Pour plus de détails, reportez-vous à la section

appelé » page 16

14 L'élément <Signature> doit inclure votre chaîne de signature API s'il s'agit du type

d'informations d'identification API que vous utilisez. Pour en savoir plus, reportez-vous au

tête SOAP », page 17

« RequesterCredentials SOAP : identifiant, mot de passe, signature et

Tableau 1.3, « Eléments d'authentification RequesterCredentials dans un en-

15 L'élément <Subject> peut indiquer un compte PayPal tiers qui vous autorise à

effectuer cette requête. Pour en savoir plus, reportez-vous au

d'authentification RequesterCredentials dans un en-tête SOAP », page 17

19 à 27 La requête SOAP de chaque API PayPal suit le modèle suivant d'attribution de nom aux

éléments. L'élément Req est ajouté au nom spécifique de l'API, et specific_api_name_Request est imbriqué dans cet élément. Chaque specific_api_name_Request a un specific_api_name_RequestType correspondant.

22 Le numéro de version de l'API SOAP de PayPal est requis pour chaque requête SOAP.

Ce numéro de version est la valeur de ns:version dans https://www.paypal.com/wsdl/PalPalSvc.wsdl

24 Pour en savoir plus sur les éléments et les valeurs obligatoires et facultatifs pour des

requêtes spécifiques, consultez la description de chaque API.

T ableau 1.3, « Eléments

20 Mai 2007 Guide de référence de l'API SOAP

Structure de la réponse

Vous trouverez ci-dessous la description annotée de la structure d'une réponse SOAP de l'API PayPal, lorsque la réponse est Success :

<?xml version=”1.0”?> <SOAP-ENV:Envelope

xmlns:SOAP-ENV=”http://schemas .xmlsoap.org/soap/env elope/” xmlns:SOAP-ENC=”http://schemas .xmlsoap.org/soap/enc oding/” xmlns:xsi=”http://www.w3.org/2 001/XMLSchema-instanc e” xmlns:xsd=”http://www.w3.org/2 001/XMLSchema” xmlns:xs=”http://www.w3.org/20 01/XMLSchema” xmlns:cc=”urn:ebay:apis:CoreCo mponentTypes” xmlns:wsu=”http://schemas.xmls oap.org/ws/2002/07 /utility” xmlns:saml=”urn:oasis:names:tc :SAML:1.0:assertion” xmlns:ds=”http://www.w3.org/20 00/09/xmldsig#” xmlns:wsse=”http://schemas.xml soap.org/ws/2002/1 2/secext” xmlns:ebl=”urn:ebay:apis:eBLBa seComponents” xmlns:ns=”urn:ebay:api:PayPalA PI”> <SOAP-ENV:Header>

<Security

xmlns=”http://schemas.xmlsoap. org/ws/2002/12/sece xt”

xsi:type=”wsse:SecurityType” /> <RequesterCredentials xmlns=”urn: ebay:api:PayPalAPI”

xsi:type=”ebl:CustomSecurityHe aderType”>

<Credentials

xmlns=”urn:ebay:apis:eBLBaseCo mponents” xsi:type=”ebl:UserIdPasswordTy pe”

/> </RequesterCredentials>

</SOAP-ENV:Header> <SOAP-ENV:Body id=”_0”>

<specific_api_name_Response xmlns=”urn:ebay:api :PayPalAPI”>

dateTime_in_UTC/GMT

</TIMESTAMP>

serviceVersion

</Version>

applicationCorrelation </CorrelationID> <Build xmlns=”urn:ebay:apis:eBLBa seComponents”>

api_build_number

</Build> <element s_for_specific_ap i_response>

data

</elements_for_specific_api_response>

</specific_api_name_Response>

Architecture de l'API SOAP de PayPal

Implémentation SOAP

Guide de référence de l'API SOAP Mai 2007 21

Architecture de l'API SOAP de PayPal

Implémentation SOAP

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

ABLEAU 1.6 Annotation d'une rép onse SOAP génériqu e

Lignes Commentaire

22 et 31 Eléments de début et de fin de specific_api_name_Response. 23 Chaque réponse API contient un horodateur avec la date et l'heure au format

UTC/GMT.

24 L'élément <Ack> contient la chaîne Success lorsque la requête correspondante a été

traitée avec succès. (Pour obtenir la liste complète des chaînes renvoyées possibles, reportez-vous à la section

En cas d'erreurs, Ack est défini sur une valeur autre que Success, et le corps de la réponse contient un élément <Errors> contenant des informations pour vous aider à déterminer la cause de l'erreur. Reportez-vous à la section

page 22

26 L'élément <CorrelationID> contient des informations sur l'application PayPal qui a

traité la requête. Utilisez la valeur de cet élément si vous devez résoudre un problème concernant l'une

de vos requêtes.

« AbstractResponseType » page 30).

« Réponses aux erreurs »

27 à 30 Chaque API PayPal renvoie une structure di fférente en fonction de ses définitions de

réponse. Pour en savoir plus, consultez la description de chaque API.

REMARQUE : le fait qu'un champ soit défini dans la structure formelle d'une réponse

Réponses aux erreurs

Si une requête est incorrecte ou si une autre erreur est détectée, le corps de la réponse SOAP contient un élément <Errors> ainsi que d'autres éléments qui peuvent vous aider à déterminer la cause de l'erreur. Les plus importants de ces autres éléments sont les suivants :

z ShortMessage z LongMessage z ErrorCode

Pour une description du contenu de ces éléments, reportez-vous à l'Annexe A, «“Codes et

messages d'erreur de toutes les API PayPal”».

L'exemple ci-après présente la réponse d'erreur qui s'affiche si votre identifiant et mot de passe API ne correspondent pas à ceux enregistrés chez PayPal.

Exemple de réponse d'erreur SOAP : Identifiant ou mot de passe incorrect

API n'implique pas forcément que ce champ soit renvoyé. Les données sont renvoyées dans une réponse uniquement si PayPal a enregistré les données associées au champ.

<?xml version="1.0" encoding=" UTF-8"?> <SOAP-ENV:Envelope details not shown>

22 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de PayPal

<SOAP-ENV:Header>... details not shown.</SOAP-E NV:Header> <SOAP-ENV:Body id="_0">

2005-02-09T21:51:26Z </Timestamp> <Ack xmlns="urn:ebay:apis:eBLB aseComponents"> Failu re</Ack> <Errors

xmlns="urn:ebay:apis:eBLBaseCo mponents"

xsi:type="ebl:ErrorType">

Authentication/Authorization F ailed

</ShortMessage>

L'identifiant ou le mot de pas se est incorrect

</LongMessage>

Error

</SeverityCode> </Errors> <Correlation ID xmlns="urn:ebay:ap is:eBLBaseComponents">

debugging_info

</CorrelationID> <Version xmlns="urn:ebay:apis:eBL BaseComponents">

1.000000 </Version> <Build xmlns="urn:ebay:apis:eBLBa seComponents">1.0006< /Build>

.. autres éléments de la réponse.

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Définitions de l'API SOAP de PayPal

CorrelationID pour signaler des problèmes à PayPal

La valeur renvoyée dans CorrelationID est importante car elle permet à PayPal de déterminer la cause précise d'une éventuelle erreur que vous pouvez rencontrer. Si vous devez résoudre un problème concernant vos requêtes, nous vous recommandons d'extraire la valeur de CorrelationID afin de la communiquer à PayPal.

Définitions de l'API SOAP de PayPal

L'API SOAP de PayPal comprend des définitions API individuelles pour des fonctions de gestion spécifiques. En tant que base, l'API repose sur la base et les principaux composants eBL (eBay Business Language). Les structures eBL principales AbstractRequestType et AbstractResponseType constituent la base de la requête et de la réponse SOAP de chaque API PayPal. AbstractResponseType est également le cadre des messages d'erreur communs à toutes les API PayPal.

Guide de référence de l'API SOAP Mai 2007 23

Architecture de l'API SOAP de PayPal

Définitions de l'API SOAP de PayPal

PayPal a pris certaines décisions concernant la conception des schémas qui peuvent influer sur la manière dont les entreprises conçoivent leurs propres applications.

z Enumérations : les énumérations sont définies directement dans le schéma de l'API PayPal. z Informations sur la résolution des problèmes : l'API PayPal renvoie des informations sur

les éléments qui ont déclenché des erreurs.

z Compatibilité en amont : la version de l'API PayPal a été mise à niveau de telle sorte que

les applications d'entreprise sont compatibles en amont lorsque de nouveaux éléments sont introduits dans le schéma côté serveur.

REMARQUE : eBL définit de nombreuses structures propre s au traitement des enchères. Ces

définitions sont contenues dans le schéma SOAP de PayPal afin de garantir une compatibilité en amont avec SOAP d'eBay et une utilisation conjointe future de SOAP sur eBay et PayPal. Les informations contenues dans ce document portent uniquement sur les définitions SOAP afférentes à l'utilisation de l'API SOAP de PayPal.

Codage de caractères, types et formats des données et devises

Cette section présente en détail le codage et les jeux de caractères, ainsi que les types et formats des données de date.

Codage de caractères UTF-8

Le service API SOAP de PayPal considère que toutes les données contenues dans les requêtes SOAP sont au format Unicode, précisément au format de codage 8 bits Unicode (ou UCS) Transformation Format (UTF-8).

Dans les réponses SOAP, le service renvoie toujours les données au format UTF-8.

Formats de date et d'heure

Le schéma API SOAP de PayPal définit les valeurs de date et d'heure comme étant Heure universelle coordonnée (UTC/GMT), utilisant le format ISO 8601, et de type ns:dateTime. Exemple d'horodatage : 2006-08-24T05:38:48Z

Ttype de données de base pour le montant des devises

Le type de données de base pour le montant des devises est appelé BasicAmountType et est dérivé d'une chaîne, et tous les éléments relatifs au montant des devises présentent la structure ci-après :

1. L'attribut currencyID est requis.

2. Le montant doit comporter deux positions décimales.

3. Le séparateur décimal doit être une virgule (« , »).

4. Vous ne devez pas utiliser de séparateur des milliers.

24 Mai 2007 Guide de référence de l'API SOAP

5. BasicAmountType a pour type de données ebl:CurrencyCodeType, qui définit un

grand nombre de codes de devises différents. Toutefois, pour que le traitement se déroule correctement, vous devez définir colonne du « Codage de caractères, types et formats des données et devises » page 24. Certaines API ne prennent en charge qu'un sous-ensemble de ces devises.

Voici un exemple. (Le nom de champ Amount est un exemple ; les noms de champs réels varient selon l'API spécifique).

API par fonction de gestion

L'API SOAP de PayPal comprend des définitions API individuelles pour des utilisations de gestion spécifiques.

TABLEAU 1.8 API par fonction de gestion

Fonction de gestion Requête/Réponse SOAP

Architecture de l'API SOAP de PayPal

Définitions de l'API SOAP de PayPal

currencyCode sur l'une des valeurs de la première

API Autorisation et collecte

API Paiement direct

API Paiement express PayPal

API GetTransaction Details

API MassPay MassPayRequest

DoCaptureRequest DoCaptureResponse DoAuthorizationRequest DoAuthorizationResponse DoVoidRequest DoVoidResponse DoReauthorizationReques DoReauthorizationResponse

DoDirectPaymentRequest DoDirectPaymentResponse

SetExpressCheckoutRequest SetExpressCheckoutResponse GetExpressCheckoutDetailsReques t GetExpressCheckoutDetailsRespon se DoExpressCheckoutPaymentRequest DoExpressCheckoutPaymentRespons e

GetTransactionDetailsRequest GetTransactionDetailsResponse

MassPayResponse

API Refund Transaction

Guide de référence de l'API SOAP Mai 2007 25

RefundTransactionRequest RefundTransactionResponse

Architecture de l'API SOAP de PayPal

Définitions de l'API SOAP de PayPal

ABLEAU 1.8 API par fonction de gestion (suite)

Fonction de gestion Requête/Réponse SOAP

API Transaction Search

TransactionSearchRequest TransactionSearchResponse

API pour échanger des fonds ou afficher des informations

Toutes les API PayPal portent sur les transactions commerciales. Toutefois, elles peuvent être classées par catégorie comme suit :

z API donnant lieu à un échange de fonds : z Autorisation et collecte z Paiement express PayPal z MassPay z RefundTransaction z API fournissant des informations sur les transactions commerciales : z GetTransactionDetails z TransactionSearch

Notification instantanée de paiement et API

L'utilisation d'une API PayPal donnant lieu à un échange de fonds déclenche l'envoi d'une notification instantanée de paiement. L'émetteur de l'appel API reçoit la notification instantanée de paiement. Les API qui envoient des notifications instantanées de paiement sont les suivantes : A l'exception de Masspay, la réponse API contient toutes les informations nécessaires à la transaction.

z DoExpressCheckoutPayment z DoDirectPayment z DoCapture z RefundTransaction z MassPay

Pour en savoir plus sur la fonction de notification instantanée de paiement, reportez-vous au

Guide d'intégration de la gestion des commandes de PayPal

26 Mai 2007 Guide de référence de l'API SOAP

Architecture de l'API SOAP de PayPal

Définitions de l'API SOAP de PayPal

Guide de référence de l'API SOAP Mai 2007 27

Architecture de l'API SOAP de PayPal

Définitions de l'API SOAP de PayPal

28 Mai 2007 Guide de référence de l'API SOAP

Structures fondamentales des

requêtes et des réponses eBL

L'API SOAP de PayPal repose sur les structures fondamentales du schéma eBL qui définit les éléments requis dans toutes les requêtes et les réponses SOAP :

z AbstractRequestType z AbstractResponseType

Schéma des principaux types eBL

Le schéma suivant représente la composition des éléments AbstractRequestType et AbstractResponseType.

FIGURE 2.1 Principaux ty pes eBL

Guide de référence de l'API SOAP Mai 2007 29

Structures fondamentales des requêtes et des réponses eBL

AbstractRequestType

AbstractRequestType est la définition type de base pour toutes les requêtes SOAP de PayPal.

IMPORTANT : vous devez définir la valeur de l'élément Version pour toutes les requêtes

sur l'une des API PayPal.

Champs

TABLEAU 2.1 Champs de AbstractRequestType

Elément Description

Version Une chaîne représentant la version du

schéma PayPal, plus précisément la valeur de l'attribut version de l'élément wsdl:definitions.

Pour connaître l'emplacement du schéma PayPal, reportez-vous à la section

« Définitions du schéma WSDL/XSD PayPal » page 14

AbstractResponseType

AbstractResponseType est la définition type de base pour toutes les réponses SOAP de PayPal.

Champs

Pour en savoir plus sur les codes et les messages d'erreur et leur signification, consultez l'

Annexe A, « Codes et messages d'erreur de toutes les API PayPal ».

Type de données

xs:string V oir le schéma

Valeurs autorisées Obligatoire ?

PayPal.

Oui

ABLEAU 2.2 Champs de Abstrac tRespon seType

Valeurs

Elément Description T ype de données

Timestamp Date et heure (UTC/GMT) de génération de la

réponse par le service SOAP de PayPal à la suite du traitement d'une requête.

30 Mai 2007 Guide de référence de l'API SOAP

xs:dateTime Transaction-

possibles

specific

Structures fondament ales des requêtes et des réponses eBL

AbstractResponseType

ABLEAU 2.2 Champs de Abstrac tRespon seType

(suite)

Elément Description T ype de données

Valeurs possibles

Ack Jeton représentant le code d'accusé de réception au

niveau de l'application. Contient l'une des valeurs énumérées suivantes :

z Su ccess : le traitement de la requête s'est

correctement déroulé.

z Fa ilure : le traitement de la requête a échoué. z Su ccessWithWarning : le traitement de la

requête s'est correctement déroulé, mais les mises en garde générées dans Errors doivent être traitées ou enregistrées par l'application demandeuse.

z Fa ilureWithWarning : le traitement de la

requête a échoué, et les erreurs et les mises en garde générées doivent être traitées par l'application demandeuse pour déterminer les causes de l'échec.

z Cu stomCode : réservé à un usage interne ou

ultérieur.

CorrelationIDChaîne identifiant la requête API exacte qui a

généré cette réponse. Nombre de caractères : 41 caractères au maximum.

Errors Code et messages d'erreur pour déboguer une

réponse.

z Er rorCode : jeton définissant le numéro du

code d'erreur.

z Sh ortMessage : chaîne contenant le message

d'erreur.

z Lo ngMessage : chaîne décrivant le message

d'erreur.

z Er rorParameters : paramètres d'erreur du

processeur de carte bancaire. Renvoyé uniquement avec DoDirectPaymentResponse.

z Se verityCode : renvoie Error ou Warning.

xs:token Success

Failure SuccessWith

Warning FailureWith

Warning CustomCode

xs:string Transaction-

specific

ns:ErrorType xs:token

Transactionspecific

xs:string xs:string ns:SeverityCod

eType

Version Une chaîne représentant la version du schéma

PayPal, plus précisément la valeur de l'attribut

xs:string Voir le schéma

PayPal

version de l'élément wsdl:definitions. Pour connaître l'emplacement du schéma PayPal,

reportez-vous à la section

schéma WSDL/XSD PayPal » page 14

Build Chaîne représentant la version logicielle spécifique

« Définitions du

xs:string

qui traite la requête et génère la réponse.

Guide de référence de l'API SOAP Mai 2007 31

Structures fondamentales des requêtes et des réponses eBL

AbstractResponseType

32 Mai 2007 Guide de référence de l'API SOAP

API Autorisation et collecte

L'API Autorisation et collecte se compose de requêtes et de réponses individuelles, comme indiqué ci-dessous.

TABLEAU 3.1 Noms, fonctions et types d'autorisation de l'API Autorisation et collecte

Utilisée avec le type

API Fonction

d'autorisation

DoCapture Régler une commande ou une transaction

DoAuthorization Autoriser une commande qui peut être honorée au-

DoVoid Annuler une commande ou une autorisation

DoReauthorization Autoriser à nouveau une transaction précédemment

REMARQUE : pour plus d'informations, reportez-vous au chapitre sur Autorisation et collecte

DoCapture

DoCaptureRequest est la requête de règlement total ou partiel d'une commande, d'une autorisation ou d'une nouvelle autorisation.

précédemment autorisée et obtenir le paiement soit du montant total, soit d'une partie du montant.

delà de 29 jours.

initiale.

autorisée.

du Guide d'intégration de Paiements express PayPal

de Paiements sur site marchand.

Autorisation de commande et autorisation de base

Autorisation de commande uniquement

Autorisation de commande et autorisation de base

Autorisation de base uniquement

ou du Guide d'intégration

REMARQUE : DoCaptureRequest est à utiliser avec les autorisations de base et de

commande.

Schéma des types de DoCapture

Le schéma suivant représente la composition des éléments de DoCaptureRequestType et DoCaptureResponseType. Les éléments obligatoires de la requête sont signalés par un

astérisque.

Guide de référence de l'API SOAP Mai 2007 33

API Autorisation et collecte

DoCapture

FIGURE 3.1 Types de DoCapture

DoCaptureRequest

Demande de collecte de fonds sur le compte d'un utilisateur PayPal.

Champs

ABLEAU 3.2 Champs de DoCaptureRequest

Champ Description Type de données

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.

xs:string Voir la

Valeurs autorisées Obligatoire ?

Oui

description.

34 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 3.2 Champs de DoCaptureRequest (suite)

Champ Description Type de données

API Autorisation et collecte

DoCapture

Valeurs autorisées Obligatoire ?

Montant 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 (.).

Complete transaction

La valeur Complete "> 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.

ebl:BasicAmount transaction

ebl:Complete CodeType

Voir la description.

Complete Not

Complete

Oui

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

Guide de référence de l'API SOAP Mai 2007 35

API Autorisation et collecte

DoCapture

ABLEAU 3.2 Champs de DoCaptureRequest (suite)

Champ Description Type de données

Valeurs autorisées Obligatoire ?

InvoiceID Votre numéro de facture ou un

autre numéro d'identification affiché pour le 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.

Remarque Note d'information sur le

règlement concerné, envoyée par email à l'émetteur du paiement et qui apparaît dans l'historique de ses transactions.

Nombre de caractères limite : 255 sicaractères d'un octet

xs:string Voir la

description.

xs:string Voir la

description.

Non

DoCaptureResponse

Réponse à DoCaptureRequest.

Champs

ABLEAU 3.3 Champs de DoCaptureRes ponse

Valeurs

Champ Description Type de données

AuthorizationID Numéro d'autorisation spécifié dans la requête.

Nombre de caractères limite : 19 caractères d'un octet au maximum

36 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la descripti on.

possibles

API Autorisation et collecte

ABLEAU 3.3 Champs de DoCaptureRes ponse (suite)

Champ Description Type de données

DoCapture

Valeurs possibles

PaymentInfo Informations concernant le paiement. ebl:PaymentInfo

Type

ABLEAU 3.4 Réponse : Champs PaymentInfoType

Champ Description Type de données

TransactionID Numéro de transaction unique du paiement.

xs:string Transaction-

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

Parent TransactionID

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

ParentTransactionID correspond au OrderID initial.

z Collecte d'une autorisation de commande. z Annulation d'une commande. La valeur de

ParentTransactionID correspond au OrderID initial.

Nombre de caractères limite : 16 chiffres au format xxxx-xxxx-xxxx-xxxx

Reportez-vous à la section

Tableau 3.4 page 37

Valeurs possibles

specific

Voir la descriptio n

ReceiptID Numéro d'avis de réception

xs:string Voir la description

Nombre de caractères limite : 16 chiffres au format xxxx-xxxx-xxxx-xxxx

TransactionType Type de transaction

z car t z exp ress-checkout

ns:Payment TransactionCode Type

Voir la descriptio n

Nombre de caractères limite 15 caractères d'un octet.

PaymentType Indique si le paiement est immédiat ou différé

Nombre de caractères limite sept caractères d'un octet

Guide de référence de l'API SOAP Mai 2007 37

ebl:PaymentCode Type

none echeck instant

API Autorisation et collecte

DoCapture

ABLEAU 3.4 Réponse : Champs PaymentInfoType (suite)

Champ Description Type de données

Valeurs possibles

PaymentDate Horodatage du paiement. Exemple :2006-08-

15T17:23:15Z

GrossAmount Montant final facturé, incluant les frais

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

xs:dateTime Transaction-

ebl:BasicAmount Type

Préférences du marchand.

FeeAmount Montant de la commission de PayPal facturée pour

la transaction

SettleAmount Montant déposé sur votre compte PayPal en cas de

conversion de devise

ebl:BasicAmount Type

TaxAmount TVA appliquée à la transaction, le cas échéant ebl:BasicAmount

Type

ExchangeRate ExTaux de change utilisé en cas de conversion de

xs:string Transaction-

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.

specific Transaction-

specific

Transactionspecific

specific

38 Mai 2007 Guide de référence de l'API SOAP

API Autorisation et collecte

ABLEAU 3.4 Réponse : Champs PaymentInfoType (suite)

Champ Description Type de données

DoCapture

Valeurs possibles

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 paieme nt est termin é et les

fonds ont été ajoutés au solde de votre compte.

z Denied : vous avez refusé le paiem e nt. 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'autorisati on 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, reportez-vous 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é.

Voided : L'autorisation pour cette transaction a été annulée.

ebl:PaymentStatus CodeType

None Canceled-

Reversal Completed Denied

Expired Failed

Pending Refunded Reversed Processed Voided

Guide de référence de l'API SOAP Mai 2007 39

API Autorisation et collecte

DoAuthorization

ABLEAU 3.4 Réponse : Champs PaymentInfoType (suite)

Champ Description Type de données

Valeurs possibles

PendingReason PendingReason est renvoyé dans la réponse

uniquement si PaymentStatus a la valeur Pending. Motif pour lequel le paiement est en attente : none: pas de motif de mise en attente.

z address : le paiement est en attente parce que

l'utilisateur n'a pas indiqué d'adresse de livraison confirmée et que vos préférences de réception de paiements sont configurées pour que vous puissiez accepter ou refuser manuellement chacun de ces paiements. Pour modifier votre préférence, accédez à la section Préférences de notification instantanée de paiement dans les Préférences de votre Préférences.

z echeck : le paiement est en attente parce qu'il a

été effectué par le biais d'un chèque électronique qui n'a pas encore été compensé.

z intl : le paiement est en attente parce que vous

détenez un compte hors des Etats-Unis et que vous ne disposez pas de système de virement. Vous devez accepter ou refuser manuellement ce paiement à partir de votre Aperçu du compte.

z multi-currency : vous ne disposez pas de solde

dans la devise qui vous a été envoyée et vos Préférences de réception de paiements ne sont pas configurées pour convertir automatiquement ce paiement et l'accepter. Vous devez accepter ou refuser manuellement ce paiement.

z verify : le paiement est en attente parce que

vous n'avez pas encore le statut Vérifié. Vous devez vérifier votre compte avant de pouvoir accepter ce paiement.

other : le paiement est en attente pour une autre raison que celles indiquées ci-dessus. Pour en savoir plus, contactez le Service clientèle de PayPal.

ebl:PendingStatus CodeType

none address echeck intl multi-currency verify other

DoAuthorization

REMARQUE : DoAuthorizationRequest doit être utilisé avec les autorisations de

commande, pas avec les autorisations de base.

40 Mai 2007 Guide de référence de l'API SOAP

DoAuthorizationRequest est votre requête concernant l'autorisation de la commande d'un utilisateur qui peut être honorée dans un délai de 29 jours. Vous utilisez DoAuthorizationRequest lorsque vous êtes prêt à expédier les produits à l'utilisateur. Une fois l'expédition effectuée, vous pouvez collecter les fonds à l'aide de DoCapture.

Pour utiliser DoAuthorization, vous devez d'abord avoir créé une commande pour un utilisateur. Pour créer une commande, vous disposez de plusieurs possibilités :

z En attribuant la valeur Order à l'élément DoExpressCheckoutPaymentRequest ou à

DoDirectPaymentRequest PaymentAction.

z Avec un panier ou une transaction Paiements sur site marchand PayPal dont la variable

HTML paymentaction a la valeur Order.

Schéma des types de DoAuthorization

Le schéma suivant représente la composition des éléments de DoAuthorizationRequestType et DoAuthorizat ionResponseType. Les éléments obligatoires de la requête sont signalés par un astérisque.

API Autorisation et collecte

DoAuthorization

FIGURE 3.2 Types de DoAuthorization

DoAuthorizationRequest

Demande d'autorisation pour tout ou partie du montant de la commande d'un utilisateur.

Guide de référence de l'API SOAP Mai 2007 41

API Autorisation et collecte

DoAuthorization

Champs

ABLEAU 3.5 Champs de DoAuthorizationRequest

Champ Description Type de données

Valeurs autorisées Obligatoire ?

TransactionIDValeur du numéro de transaction de la

commande renvoyée par PayPal

Nombre de caractères limite : caractères d'un octet au maximum

Amount 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 (.).

Transaction Entity

Type de transaction à autoriser. La seule valeur acceptable est Order, qui signifie que la transaction représente la commande d'un utilisateur qui peut être honorée au-delà de 29

DoAuthorizationResponse

Réponse à DoAuthorizationRequest.

xs:string Voir la description. Oui

ebl:BasicAmount Type

ebl:Transaction EntityType

Voir la description. Oui

Order Non

Champs

ABLEAU 3.6 Champs de DoAutho rizationRespo nse

Valeurs

Champ Description Type de données

TransactionIDNuméro d'identification d'autorisation.

Nombre de caractères limite 19 caractères d'un octet.

Amount Montant spécifié dans la requête. ebl:BasicAmount

42 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la description.

Type

possibles

Voir la description.

DoVoid

DoVoidRequest annule une commande ou une autorisation.

IMPORTANT : la valeur AuthorizationID spécifiée pour DoVoidRequest doit être le

numéro d'autorisation initial, pas la valeur de AuthorizationID renvoyée par DoReauthorizationResponse.

Par définition, lorsque le délai d'autorisation expire, l'autorisation ou la nouvelle autorisation d'une transaction est implicitement annulée.

REMARQUE : DoVoidRequest est à utiliser avec les autorisations de base et de commande.

Schéma des types de DoVoid

Le schéma suivant représente la composition des éléments de DoVoidRequestType et DoVoidResponseType. Les éléments obligatoires de la requête sont signalés par un

astérisque.

API Autorisation et collecte

DoVoid

FIGURE 3.3 Types de DoVoid

DoVoidRequest

Demande d'annulation d'une autorisation.

Guide de référence de l'API SOAP Mai 2007 43

API Autorisation et collecte

DoVoid

Champs

ABLEAU 3.7 Champs de DoVoidRequest

Champ Description T ype de données

Valeurs autorisées Obligatoire ?

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

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

DoVoidResponse

Réponse à DoVoidRequest.

xs:string Voir la

description.

xs:string Voir la

description.

Oui

Non

Champs

ABLEAU 3.8 Champs de DoVoidResponse

Valeurs

Champ Description Type de données

AuthorizationIDNuméro d'autorisation spécifié dans la

requête. Nombre de caractères limite : 19 Numéro

caractères d'un octet.

44 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la description.

possibles

DoReauthorization

REMARQUE : DoReauthorization doit être utilisé uniquement avec les autorisations de

base, pas avec les autorisations de commande.

Pour utiliser DoReauthorization vous devez avoir au préalable autorisé une transaction, qui doit avoir dépassé son délai de règlement. L'appel de DoReauthorization sur une transaction correcte échouera. Vous pouvez autoriser une transaction de plusieurs manières :

z A partir de l'onglet Outils marchands de votre compte marchand PayPal. z En attribuant la valeur Authorization à l'élément

DoExpressCheckoutPaymentRequest PaymentAct ion.

z Avec une transaction de panier (comme celles utilisées par Paiements sur site marchand

PayPal) dont la variable HTML paymentaction a la valeur Authorization .

Vous pouvez invo quer DoReauthorization autant de fois que nécessaire pour obtenir une seule nouvelle autorisation réussie. Lorsque DoReauthorization renvoie un message de réussite, le délai de règlement est réinitialisé, vous pouvez collecter les fonds, mais vous ne pouvez plus demander de nouvelle autorisation.

API Autorisation et collecte

DoReauthorization

Schéma des types de DoReauthorization

Le schéma suivant représente la composition des éléments de DoReauthorizationRequestType et DoReauthoriza tionResponseType. Les éléments obligatoires de la requête sont signalés par un astérisque.

FIGURE 3.4 Types de DoReauthorization

DoReauthorizationRequest

Requête concernant l'utilisation de Autorisation et collecte pour autoriser à nouveau une transaction.

Guide de référence de l'API SOAP Mai 2007 45

API Autorisation et collecte

DoReauthorization

Champs

ABLEAU 3.9 Champs de DoReauthorization Requ est

Champ Description Type de données

Valeurs autorisées Obligatoire ?

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

Amount 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 (.).

DoReauthorizationResponse

Réponse à DoReauthorizationRequest.

Champs

xs:string N'importe quel

numéro de transaction PayPal préalablement autorisée.

eBL:BasicAmount Type

Voir la description. Oui

Oui

ABLEAU 3.10 Champs d e DoReaut horizationRes ponse

Valeurs

Champ Description Ty pe de données

Authorizati on ID

46 Mai 2007 Guide de référence de l'API SOAP

Nouveau numéro d'autorisation. Nombre de caractères limite : 19 caractères d'un

octet.

xs:string Voir la description.

possibles

API Paiement express PayPal

L'API Paiement express PayPal est la solution alternative à la fonction Panier standard de PayPal dans les Paiements sur site marchand.

IMPORTANT : pour une description détaillée de l'utilisation de Paiement express PayPal,

reportez-vous au Guide d'intégration de Paiement express PayPal.

L'API Paiement express PayPal est constituée de trois requêtes SOAP que vous faites aux trois points d'intégration pendant le paiement d'un client. Le client est également redirigé vers PayPal. Voici la succession d'étapes :

1. SetExpressCheckout

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

3. GetExpressCheckoutDetails

4. DoExpressCheckoutPayment

IMPORTANT : pour tous les champs relatifs au montant des devises des trois API Paiement

express PayPal, l'attribut currencyID doit être défini sur l'un des codes des devises acceptées. Pour une session de paiement concernant un acheteur, ne mélangez pas les devises au sein d'une même requête SOAP ou entre les requêtes SOAP. Par exemple, n'attribuez pas la valeur USD à currencyID dans une requête et la valeur GBP dans une autre requête concernant le même acheteur.

Paiement express PayPal pour les enchères eBay

Pour utiliser Paiement express PayPal avec les enchères eBay, vous avez plusieurs champs supplémentaires que vous pouvez définir pour contrôler le comportement de Paiement express PayPal :

1. Dans SetExpressCheckout :

– ChannelType a la valeur eBayItem

2. Dans DoExpressCheckoutPayment :

– PaymentAction doit avoir la valeur Sale – EbayItemPaymentDetailsItem.ItemNumber – EbayItemPaymentDetailsItem.AuctionTransactionID – EbayItemPaymentDetailsItem.OrderID

Guide de référence de l'API SOAP Mai 2007 47

API Paiement express PayPal

SetExpressCheckout

SetExpressCheckout indique à PayPal que vous utilisez Paiement express PayPal pour obtenir le paiement auprès de votre client.

Schéma des types de Set ExpressCheckout

Le schéma suivant représente la composition des éléments de SetExpressCheckoutRequestType et SetExpres sCheckoutResponseType. Les éléments obligatoires de la requête sont signalés par un astérisque.

48 Mai 2007 Guide de référence de l'API SOAP

FIGURE 4.1 Types de SetExpressCheckout

API Paiement express PayPal

SetExpressCheckout

SetExpressCheckoutRequest

Requête pour utiliser la fonction Paiement express PayPal de PayPal afin d'obtenir le paiement.

IMPORTANT : les champs des fichiers WSDL ou XSD qui ne sont pas décrits ici sont

ignorés. Par exemple, ne définissez pas CountryName.

Guide de référence de l'API SOAP Mai 2007 49

API Paiement express PayPal

SetExpressCheckout

Champs

ABLEAU 4.1 Champs de SetExpress Checkou tReques t

Champ Description

Type de données Valeurs autorisées Obligatoire ?

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

OrderTotal Coût total de la commande pour le

client. Si vous connaissez les frais d'expédition, de livraison et de TV A, 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 une virgule (,).

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

ebl:Express CheckoutTokenT ype

cc:BasicAmount Type

Consultez la description du

Tableau 4.3,

Non

« Champs de SetExpressCheckout Response »

Voir la description. Oui

50 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

API Paiement express PayPal

SetExpressCheckout

Type de données Valeurs autorisées Obligatoire ?

MaxAmount 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

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

Order Description

Description des objets achetés par le client.

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

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 la réponse.

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

cc:BasicAmount

Voir la description. Non

Type

xs:string Voir la description. Non

InvoiceID Votre numéro de facture ou de suivi

xs:string Voir la description. Non personnel. PayPal vous renvoie cette valeur dans la réponse.

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

Guide de référence de l'API SOAP Mai 2007 51

API Paiement express PayPal

SetExpressCheckout

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

Type de

données Valeurs autorisées Obligatoire ?

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.

xs:string Voir la description. Oui

Address Adresse de livraison du client.

REMARQUE : si vous incluez une

adresse de livraison et que vous définissiez l'élément AddressOverride dans la requête, PayPal renvoie cette même adresse dans

ebl:Address

Type

Reportez-vous au

Tableau 4.2 page 57.

Non

GetExpressCheckoutDet ailsResponse

52 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

API Paiement express PayPal

SetExpressCheckout

Type de

données Valeurs autorisées Obligatoire ?

ReqConfirm Shipping

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.

NoShipping La valeur 1 indique qu'aucun 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.

Address Override

La valeur 1 indique que les pages de PayPal doivent afficher l'adresse de livraison que vous avez définie dans la requête SetExpressCheckout, et non celle enregistrée chez PayPal pour ce client.

REMARQUE : le fait d'afficher

l'adresse postale enregistrée chez PayPal ne permet pas au client de modifier cette adresse.

xs:string 0

Non

Guide de référence de l'API SOAP Mai 2007 53

API Paiement express PayPal

SetExpressCheckout

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

Type de

données Valeurs autorisées Obligatoire ?

LocaleCode Paramètre régional des pages

affichées par PayPal pendant 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, reportezvous au

pays”

Chapter F, “Codes

xs:string Voir la description. Non

PageStyle Détermine le style personnalisé des

xs:string Voir la description. Non 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.

54 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

API Paiement express PayPal

SetExpressCheckout

Type de

données Valeurs autorisées Obligatoire ?

cpp-headerimage

cpp-headerborder-color

cpp-headerback-color

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

Définit la couleur de bordure de l'entête de la page de paiement. La 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.

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

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

xs:string Voir la description. Non

cpp-payflowcolor

Guide de référence de l'API SOAP Mai 2007 55

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

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

xs:string Voir la description. Non

API Paiement express PayPal

SetExpressCheckout

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

Type de

données Valeurs autorisées Obligatoire ?

Payment Action

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 PayPal Autorisation et collecte.

z S ale 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

DoExpressCheckoutPaymen t de l'API finale.

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

ebl:Payment

ActionCodeType

xs:token

Par défaut : la transaction résultant de

DoExpress Checkout Payment Request est une vente

finale.

Authorization

Commande

Sale

Non

BuyerEmail Adresse email de l'acheteur entrée

pendant le paiement. PayPal utilise

ebl:Email

AddressType

Voir la description. Non

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

SolutionType Type de procédure de paiement :

z Sole : Paiement express PayPal

eBL:Solution

TypeType

pour les enchères

z Mark : Paiement express PayPal

normal

LandingPage Type de page PayPal à afficher :

z Billing : compte non-PayPal z Login : connexion au compte

eBL:Landing

PageType

PayPal

56 Mai 2007 Guide de référence de l'API SOAP

Sole Mark

Facturation Mark

Non

ABLEAU 4.1 Champs de SetExpress Checkou tReques t (suite)

Champ Description

API Paiement express PayPal

SetExpressCheckout

Type de

données Valeurs autorisées Obligatoire ?

ChannelType Type de canal :

z Merchant : vendeur non enchères z eBayItem : enchère eBay

PromoCode Code financier promotionnel des

services du marchand

REMARQUE : les éléments de AddressType sont obligatoires uniquement si vous incluez

l'élément Address dans la requête SOAP.

IMPORTANT : les champs des fichiers WSDL ou XSD qui ne sont pas décrits ici sont

ignorés. Par exemple, ne définissez pas CountryName.

ABLEAU 4.2 Adresse (ad resse de livraiso n) : é léments de Address Type

Champ Descriptions

Name Nom de la personne associée à cette

adresse de livraison. Nombre de caractères limite :

32 caractères d'un octet.

Street1 Première adresse postale.

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

eBL:Channel

Type

Le marchand eBayItem

Non

xs:string Un code valable Non

Type de données

xs:string Voir la

Valeurs autorisées Obligatoire ?

Oui

description.

xs:string Voir la

Oui

description.

Street2 Seconde adresse postale.

Nombre de caractères limite :

xs:string Voir la

description.

Non

100 caractères d'un octet.

CityName Nom de la ville.

Nombre de caractères limite :

xs:string Voir la

description.

Oui

40 caractères d'un octet.

StateOr Province

Etat ou province. Nombre de caractères limite :

40 caractères d'un octet. Requis pour les adresses américaines

(USA) seulement.

PostalCode Code postal américain ou code postal

spécifique aux autres pays.

xs:string Reportez-vous à

Annexe E, “Abréviations des états et provinces

xs:string Voir la

description.

Non

Oui

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

Guide de référence de l'API SOAP Mai 2007 57

API Paiement express PayPal

GetExpressCheckoutDetails

ABLEAU 4.2 Adresse (ad resse de livraiso n) : é léments de Address Type (suite)

Champ Descriptions

Country Code pays.

Nombre de caractères : deux caractères d'un octet.

Phone Numéro de téléphone.

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

Type de données

ebl:Countr yCode Type

xs:string

xs:string Voir la

Valeurs autorisées Obligatoire ?

Reportez-vous à l'

Annexe F, “Codes pays

description.

SetExpressCheckoutResponse

Réponse à SetExpressCheckoutRequest.

Champs

ABLEAU 4.3 Champs de SetExpress Checkou tRespon se

Champ Description Ty pe de données Valeur

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

xs:string Voir la description.

Oui

Non

GetExpressCheckoutDetails

GetExpressCheckoutDetails renvoie les informations sur le client, y compris son nom et son adresse enregistrés chez PayPal.

Schéma des types de GetExpressCheckoutDetails

Le schéma suivant représente la composition des éléments de

GetExpressCheckoutDetailsRequestType et GetExpressCheckoutDetailsResponseType.

58 Mai 2007 Guide de référence de l'API SOAP

API Paiement express PayPal

GetExpressCheckoutDetails

Les éléments obligatoires de la requête sont signalés par un astérisque.

FIGURE 4.2 Types de GetExpressCheckout

GetExpressCheckoutDetailsRequest

Obtient des détails sur un paiement qui doit être traité par la fonction Paiement express PayPal de PayPal.

Guide de référence de l'API SOAP Mai 2007 59

API Paiement express PayPal

GetExpressCheckoutDetails

Champs

ABLEAU 4.4 Champs de GetExpre ssChecko utDetailsRe quest

Champ Description

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.

Type de données

xs:string Jeton non expiré Oui

Valeurs autorisées Obligatoire ?

GetExpressCheckoutDetailsResponse

Réponse à GetExpressCheckoutDetailsRequest.

Champs

ABLEAU 4.5 Champs de GetExpre ssChecko utDetailsRe sponse

Champ Description Ty pe de données

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.

xs:string Consultez la

Valeurs possibles

description du

Tableau 4.3, « Champs de SetExpressCheck outResponse »

PayerInfo Informations concernant le payeur. ebl:PayerInfo

Type

Reportez-vous à la section

Tableau 4.6 page 61

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.

60 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la description.

API Paiement express PayPal

GetExpressCheckoutDetails

ABLEAU 4.5 Champs de GetExpre ssChecko utDetailsRe sponse (su ite)

Champ Description Ty pe de données

Valeurs possibles

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

ContactPhone

Numéro de téléphone à contacter du payeur.

IMPORTANT : 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-XXX-XXXX (pour les numéros aux Etats-Unis) ou +XXX XXXXXXXX (pour les autres numéros)

REMARQUE : des éléments vides sont renvoyés s'il n'existe pas de données représentatives

pour le client. Par exemple, si le client ne représente pas une entreprise (et n'a donc pas de raison sociale enregistrée chez PayPal), l'élément renvoyé n'a pas de valeur : <PayerBusiness/>.

ABLEAU 4.6 Réponse : éléments de PayerInfoType

xs:string Voir la description.

Valeurs

Champ Description DataType

Payer Adresse email du payeur.

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

PayerID Numéro de compte unique du client PayPal.

ebl:EmailAddre ss Type

ebl:UserIDType Voir la description.

possibles

Voir la descripti on.

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.

PayerName Nom et prénom du payeur. ebl:PersonName

ebl:PayPalUser StatusCodeType

Type

verified unverified

Reportez-vous à la section

Tableau 4.7 page 62

Guide de référence de l'API SOAP Mai 2007 61

API Paiement express PayPal

GetExpressCheckoutDetails

ABLEAU 4.6 Répons e : élé ments de Pay erInfoType (suite)

Champ Description DataType

Valeurs possibles

Payer Country

Payer Business

Address Informations concernant l'adresse de livrai son du

Champ Description DataType

Salutation Formule d'appel du payeur.

FirstName Prénom du payeur.

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.

Raison sociale du payeur. Nombre de caractères limite : 127 caractères d'un

octet.

payeur.

ABLEAU 4.7 Réponse : éléments de PayerName

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

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

ebl:CountryCod e Type

xs:string Voir la description.

xs:string Reportez-vous à la

xs:string Voir la description.

ebl:PersonName Type

Reportez-vous à l'

Annexe F,

“Codes pays

section

Tableau 4.8 page 62

Valeurs possibles

Voir la descripti on.

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.

ABLEAU 4.8 Répons e : champs de AddressType

Champ Descriptions T ype de données

Address Status

62 Mai 2007 Guide de référence de l'API SOAP

Etat de l'adresse postale enregistrée chez PayPal ebl:AddressStatus

ebl:NameType Voir la description.

ebl:SuffixType Voir la description.

Valeurs possibles

none

TypeCode

Confirmed Unconfirmed

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.8 Répons e : champs de AddressType (suite)

Champ Descriptions T ype de données

Valeurs possibles

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

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

Street1 Première adresse postale.

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

Street2 Seconde adresse postale.

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

CityName Nom de la ville.

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

StateOr Province

Etat ou province.

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

Reportez-vous à l'Annexe E, “Abréviations des

états et provinces

PostalCode Code postal américain ou code postal spécifique

aux autres pays.

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

xs:string Voir la description.

Country Code pays.

Nombre de caractères : deux caractères d'un octet.

ebl:Country Code Type

xs:string

Reportez-vous à l'

Annexe F,

“Codes pays

DoExpressCheckoutPayment

Avec DoExpressCheckoutPayment, vous obtenez un paiement via Paiement express PayPal pour une vente finale ou vous demandez une autorisation pour collecte ultérieure du paiement.

Schéma des types de DoExpressCheckoutPayment

Le schéma suivant représente la composition des éléments de

DoExpressCheckoutPaymentRequestType et DoExpressCheckoutPaymentResponseType. Les éléments obligatoires de la requête sont

signalés par un astérisque.

Guide de référence de l'API SOAP Mai 2007 63

API Paiement express PayPal

DoExpressCheckoutPayment

FIGURE 4.3 Types de DoExpressCheckoutPayment

DoExpressCheckoutPaymentRequest

Requête pour obtenir le paiement via la fonction Paiement express PayPal de PayPal.

IMPORTANT : PayPal exige qu'un marchand utilisant la fonction Paiement express PayPal

affiche pour le client un montant identique à celui qu'il envoie à PayPal dans l'élément OrderTotal avec l'API DoExpressCheckoutPaymentRequest.

64 Mai 2007 Guide de référence de l'API SOAP

API Paiement express PayPal

Champs

ABLEAU 4.9 Champs de DoExpressChe ckoutPay mentReq uest

Champ Description T ype de données

DoExpressCheckoutPayment

Valeurs autorisées Obligatoire ?

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.

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 Autorisation et collecte.

z Sa le indique qu'il s'agit d'une vente

finale pour laquelle vous demandez un paiement.

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

Checkout

PayPal Express

xs:string Voir la description. Oui

ebl:Payment ActionCodeType

xs:token

Par défaut : la transaction résultant de

Oui

DoExpress Checkout Payment Request est une

vente finale.

Authorization

Commande

Sale

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

PayerID Numéro d'identification unique du

ebl:UserIDType Voir la description. Oui compte client PayPal renvoyé par la réponse GetExpressCheckoutDetails.

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

Payment Details

Guide de référence de l'API SOAP Mai 2007 65

Informations concernant le paiement ebl:Payment

Details

Type

Reportez-vous à la section

Tableau 4.10 page 66

Oui

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.10 Requê te : champs de Paym entDetailsType

Champ Description Type de données

Valeurs autorisées Obligatoire ?

OrderTotal Total de la commande , incluant les

frais d'expédition et de livraison, de dossier et le montant de la TVA.

REMARQUE : limites : ne doit

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

ItemTotal 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 facultatif doit être une virgule (,).

ebl:BasicAmount Type

Voir la description. Oui

Voir la description. Non

66 Mai 2007 Guide de référence de l'API SOAP

API Paiement express PayPal

ABLEAU 4.10 Requê te : champs de Paym entDetailsType (suite)

Champ Description Type de données

DoExpressCheckoutPayment

Valeurs autorisées Obligatoire ?

Shipping Total

Handling Total

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

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

Total des frais de dossier de cette commande.

REMARQUE : nombre de caractères

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

ebl:BasicAmount Type

Voir la description. Non

Guide de référence de l'API SOAP Mai 2007 67

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.10 Requê te : champs de Paym entDetailsType (suite)

Champ Description Type de données

Valeurs autorisées Obligatoire ?

TaxTotal Somme des frais de TVA de tous les

objets de cette commande.

REMARQUE : nombre de caractères

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

Le code de devise doit être le même que celui défini pour OrderTotal.

Order Description

Description des objets achetés par le client.

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

ebl:BasicAmount Type

xs:string Voir la description. Non

Voir la description. Non

Custom Champ à structure non imposée que

vous utilisez librement. Nombre de caractères limite :

256 caractères alphanumériques d'un octet.

InvoiceID Votre numéro de facture ou de suivi

personnel.

xs:string Voir la description. Non

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.

68 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la description. Non

API Paiement express PayPal

ABLEAU 4.10 Requê te : champs de Paym entDetailsType (suite)

Champ Description Type de données

DoExpressCheckoutPayment

Valeurs autorisées Obligatoire ?

NotifyURL Votre URL pour la réception de la

Notification instantanée de paiement (NIP) concernant cette transaction.

IMPORTANT : 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 alphabétiques d'un octet.

ShipTo Address

Payment Details Objet

Adresse de livraison de la commande. ebl:AddressType Reportez-vous à la

Détails sur chaque objet inclus dans la commande.

xs:string Voir la description. Non

Non

section

Tableau 4.11

Non

ebl:PaymentD etailsItemType

page 69

Reportez-vous à la section

Tableau 4.12 page 70

PromoCode Code financier promotionel des

services du marchand

REMARQUE : les éléments de AddressType sont obligatoires uniquement si vous incluez

xs:string Un code valable Non

l'élément Address dans la requête SOAP.

IMPORTANT : dans le tableau suivant, les champs des fichiers WSDL ou XSD qui ne sont

pas décrits ici sont ignorés. Par exemple, ne définissez pas CountryName.

ABLEAU 4.11 Requê te : ShipToAddress : champs de AddressType

Champ Descriptions T ype d e données

Name Nom de la personne associée à

cette adresse. Nombre de caractères limite :

32 caractères d'un octet.

xs:string Voir la description. Oui

Valeurs autorisées Obligatoire ?

Guide de référence de l'API SOAP Mai 2007 69

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.11 Requê te : ShipToAddress : champs de AddressType (suite)

Champ Descriptions T ype d e données

Valeurs autorisées Obligatoire ?

Street1 Première adresse postale.

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

Street2 Seconde adresse postale.

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

CityName Nom de la ville.

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

StateOr Province

PostalCode Code postal américain ou code

Country Code pays.

Etat ou province. Nombre de caractères limite :

40 caractères d'un octet. Requis pour les adresses

américaines (USA) seulement.

postal spécifique aux autres pays. Nombre de caractères limite :

20 caractères d'un octet.

Nombre de caractères : deux caractères d'un octet.

xs:string Voir la description. Oui

xs:string Voir la description. Non

xs:string Voir la description. Oui

xs:string Reportez-vous à

Annexe E,

Non

“Abréviations des états et provinces

xs:string Voir la description. Oui

ebl:Country Code Type

xs:string

Reportez-vous à l'

Annexe F,

“Codes pays

Oui

Phone Numéro de téléphone.

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

ABLEAU 4.12 Requête : champs de PaymentDetailsItemType

Champ Description Type de données

Name Nom de l'objet

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

70 Mai 2007 Guide de référence de l'API SOAP

xs:string Voir la description. Non

Valeurs autorisées Obligatoire ?

xs:string Voir l a

description.

Non

API Paiement express PayPal

ABLEAU 4.12 Requête : champs de PaymentDetailsItemType (suite)

Champ Description Type de données

DoExpressCheckoutPayment

Valeurs autorisées Obligatoire ?

Amount Coût de l'objet.

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.

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

Number Numéro de l'objet.

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

Quantity Quantité d'objets.

Nombre de caractères limite : n'importe quel chiffre entier positif.

Tax TVA concernant l'objet.

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.

REMARQUE : vovs devez définir

l'attribut currencyID sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal.

ebl:BasicAmount Type

Voir la description.

xs:string Voir l a

description.

xs:string Voir l a

description.

ebl:BasicAmount Type

Voir la description.

Non

EbayItem Payment DetailsItem

Guide de référence de l'API SOAP Mai 2007 71

Informations concernant une vente aux enchères sur eBay.

eBl:ebayItem PaymentDetails ItemType

Reportez-vous au

Tableau 4.13 page 72

Non

API Paiement express PayPal

DoExpressCheckoutPayment

Si vous transmettez le fichier EbayItemPaymentDetailsItem, vous devez affecter à ChannelType la valeur eBayItem et à PaymentAction la valeur Sale.

ABLEAU 4.13 Requê te : champs de EbayIte mPayme ntDetailsIte mType

Champ Description

ItemNumber Numéro de l'enchère/de l'objet

Nombre de caractères : 765 caractères d'un octet.

Auction API Transaction ID

OrderID Numéro de commande de la vente aux

Numéro de transaction de la vente aux enchères.

Nombre de caractères : 255 caractères d'un octet.

enchères. Nombre de caractères : 64 caractères d'un

octet.

DoExpressCheckoutPaymentResponse

Réponse à DoExpressCheckoutPaymentRequest.

Champs

Type de données

xs:string Voir l a

xs:string Voir la

xs:string Voir l a

Valeurs autorisées Obligatoire ?

description.

Non

ABLEAU 4.14 Champs d e DoExpressCh eckout Payment Resp onse

Valeurs

Champ Description Type de données

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.

PaymentInfo Informations concernant le paiement. ebl:PaymentInfo

xs:string Consultez la

Type

possibles

description du

Tableau 4.3, « Champs de SetExpressCheck outResponse »

Reportez-vous à la section

Tableau 4.15 page 73

72 Mai 2007 Guide de référence de l'API SOAP

API Paiement express PayPal

DoExpressCheckoutPayment

TABLEAU 4.15 Réponse : éléments de PaymentInfoType

Elément Description Type de données

Valeurs possibles

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

API Transaction Type

PaymentType Indique si le paiement est immédiat ou différé.

T ype de transaction .

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

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

PaymentDate

GrossAmount Montant final facturé, incluant les frais

Horodatage du paiement. xs:dateTime Transaction-

d'expédition, de livraison et de TVA de vos Préférences du marchand.

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 ( .). Equivalen t à neuf caractères au maximum pour USD.

xs:string Transaction-

specific

ns:Payment TransactionCode Type

ebl:PaymentCode Type

xs:string

ebl:BasicAmount Type

cart express-

checkout

none echeck instant

specific Transaction-

specific

FeeAmount Montant de la commission de PayPal facturée pour

la transaction.

ebl:BasicAmount Type

Transactionspecific

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.

Settle Amount

Guide de référence de l'API SOAP Mai 2007 73

Montant déposé sur votre compte PayPal après conversion de devise.

ebl:BasicAmount Type

Transactionspecific

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.15 Répon se : éléments de PaymentInfo Type (suite)

Elément Description Type de données

Valeurs possibles

TaxAmount TVA facturée pour la transaction.

Exchange Rate

Payment Status

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.

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.

ebl:BasicAmount Type

xs:string

xs:string Transaction-

ebl:Payment StatusCodeType

xs:token

Transactionspecific

specific

Completed Pending

74 Mai 2007 Guide de référence de l'API SOAP

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.15 Répon se : éléments de PaymentInfo Type (suite)

Elément Description Type de données

Valeurs possibles

Pending Reason

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

Préférences de notification 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.

ebl:Pending Status CodeType

xs:token

none address echeck intl multi-

currency verify other

Guide de référence de l'API SOAP Mai 2007 75

API Paiement express PayPal

DoExpressCheckoutPayment

ABLEAU 4.15 Répon se : éléments de PaymentInfo Type (suite)

Elément Description Type de données

Valeurs possibles

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 ot her : cette transaction a été annulée pour un

motif autre que celles indiquées ci-dessus.

ebl:ReasonCodeT ype

xs:token

none

chargeback

guarantee buyer-

complaint

refund

other

76 Mai 2007 Guide de référence de l'API SOAP

API GetTransactionDetails

L'API GetTransactionDetails extrait les informations sur une transaction unique.

Schéma des types de GetTransactionDetails

Le schéma suivant représente la composition des éléments de GetTransactionDetailsRequestType et GetTra nsactionDetailsResponseType.

Guide de référence de l'API SOAP Mai 2007 77

API GetTransactionDetails

GetTransactionDetailsRequest

FIGURE 5.1 Types de GetTransactionDetails

GetTransactionDetailsRequest

Obtient les détails sur une transaction.

78 Mai 2007 Guide de référence de l'API SOAP

Champs

API GetTransactionDetails

GetTransactionDetailsResponse

TABLEAU 5.1 Champs de GetTransactionDetailsRequ est

Champ Description

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

GetTransactionDetailsResponse

Réponse à GetTransactionDetailsRequest.

REMARQUE : le fait qu'un champ soit défini dans la structure formelle de

GetTransactionDetailsResponse ne signifie pas forcément que ce champ sera renvoyé. Les données sont renvoyées dans une réponse uniquement si PayPal a enregistré les données associées au champ.

Type de données

xs:string Spécifique à

Valeurs possibles Obligatoire ?

la transaction

Oui

Champs

Pour les codes et les messages d'erreur et leur signification, reportez-vous à l'Annexe A, « Code s et messages d'erreur de toutes les API PayPal ».

ABLEAU 5.2 Champs de GetTransactionDetailsRespon se

T ype de données et valeurs

Champ Elément inclus Description

Paiement API Transaction Détails

ReceiverInfo Contient les éléments décrits ci-dessous. ebl:ReceiverIn

Guide de référence de l'API SOAP Mai 2007 79

ReceiverInfo PayerInfo PaymentInfo PaymentItemInfo

Wrapper

possibles

foType

API GetTransactionDetails

GetTransactionDetailsResponse

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

T ype de données et valeurs possibles

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

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

ReceiverID Numéro de compte unique du destinataire du

paiement (le vendeur). Cette valeur est identique à celle du code parrainage du destinataire.

PayerInfo Contient les éléments décrits ci-dessous. ebl:PayerInfo

Payer Adresse email du payeur.

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

xs:string

Type ns:Email

Address Type

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é

PayerName

(inclus dans PayerInfo)

80 Mai 2007 Guide de référence de l'API SOAP

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.

ebl:UserIDType

ebl:PayPalUser StatusCodeType

Vérifié Non-Vérifié

xs:string

ebl:NameType

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

API GetTransactionDetails

GetTransactionDetailsResponse

T ype de données et valeurs possibles

Address (inclus dans

PayerInfo)

LastName Nom du payeur.

ebl:NameType

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

Suffix Suffixe du payeur.

ebl:SuffixType

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

PayerCountry Pays de résidence de l'expéditeur du paiemen t,

indiqué par un code pays ISO 3166 à deux

ebl:Country CodeType

caractères. Nombre de caractères limite : deux caractères d'un

octet.

PayerBusiness Raison sociale du payeur.

xs:string

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

Contient les éléments ci-après. ebl:Address

Type

AddressOwner Société eBay qui gère cette adresse. ebl:Address

OwnerTypeCode xs:token eBay PayPal

AddressStatus Etat de l'adresse enregistrée chez PayPal :

Non Confirmed Unconfirmed

ebl:AddressSta tus CodeType

xs:token Non Confirmed Unconfirmed

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

xs:string

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

Street1 Première adresse postale.

xs:string

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

Guide de référence de l'API SOAP Mai 2007 81

API GetTransactionDetails

GetTransactionDetailsResponse

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

T ype de données et valeurs possibles

Street2 Seconde adresse postale.

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

CityName Nom de la ville.

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

StateOrProvince Etat ou province.

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

Consultez l'

et provinces »

Country Pays de l'adresse de livraison du payeur au format

code pays standard de deux caractères ISO3166. Nombre de caractères limite : deux caractères d'un

octet.

CountryName Nom complet du pays.

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

Phone Numéro de téléphone associé à cette adresse. xs:string PostalCode Code postal. xs:string

Annexe E, « Abréviations des états

xs:string

ns:Country

xs:string

PaymentInfo Contient les éléments ci-après. ebl:Payment

Info Type

82 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

API GetTransactionDetails

GetTransactionDetailsResponse

T ype de données et valeurs possibles

Parent TransactionID

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

ParentTransactionID correspond au OrderID initial.

z Collecte d'une autorisation de commande. z Annulation d'une commande. La valeur de

ParentTransactionID correspond au OrderID initial.

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

TransactionID Numéro de transact ion 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.

xs:string

Guide de référence de l'API SOAP Mai 2007 83

API GetTransactionDetails

GetTransactionDetailsResponse

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

T ype de données et valeurs possibles

TransactionType Type 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é. virtual-terminal : transaction créée via le

terminal virtuel du marchand.

PaymentType Indique si le paiement est immédiat ou différé.

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

ebl:Payment Transaction Code transaction

xs:token cart send_money web-accept subscr-failed subscr-cancel subscr-payment subscr-signup subscr-eot subscr-modify mercht-pmt mass-pay virtual-

terminal express-

checkout ebl:Payment

Code transaction

xs:string none echeck instant

PaymentDate Date et heure du paiement. xs:dateTime GrossAmount Montan t to tal du paiement du client, avant

soustraction des commissions sur les transactions.

FeeAmount Commissions sur transaction associées au

paiement.

SettleAmount Montant déposé sur le sold e principal du compte

après conversion automatique de la devise (par le biais de vos Préférences de récept ion de paiements) ou conversion manuelle (en acceptant manuellement un paiement). Ce montant est calculé après évaluation des frais et des taxes.

TaxAmount Montant des taxes po ur la transaction. xs:string

84 Mai 2007 Guide de référence de l'API SOAP

xs:string

ebl:Basic Amount Type

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

API GetTransactionDetails

GetTransactionDetailsResponse

T ype de données et valeurs possibles

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

xs:string

ebl:Payment Status CodeType

xs:token None Canceled-

Reversal Completed Denied Expired Failed

In-Progress Partially-

Refunded

Pending Processed Refunded Reversed Voided

Guide de référence de l'API SOAP Mai 2007 85

API GetTransactionDetails

GetTransactionDetailsResponse

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

T ype de données et valeurs possibles

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

Préférences de notification 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 d e 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.

ebl:Pending Status CodeType

xs:token none authorization address echeck intl multi-currency unilateral upgrade verify other

86 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

API GetTransactionDetails

GetTransactionDetailsResponse

T ype de données et valeurs possibles

PaymentItem Info

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 ot her : cette transaction a été annulée pour un

motif autre que celles indiquées ci-dessus.

Contient les éléments ci-après. ebl:Payment

InvoiceID 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

initiale. Nombre de caractères limite : 127 caractères

alphanumériques d'un octet.

ebl:ReasonCode Type

xs:token none rejet de débit guarantee buyer-

complaint remboursement other

ItemInfoType xs:string

xs:string

Memo Mémo saisi par votre client dans le champ note

xs:string

des paiements sur site marchand de PayPal. Nombre de caractères limite : 255 caractères

alphanumériques d'un octet.

PaymentItem SaleTax Montant des taxes débitées pour le paiement. xs:string

Name Nom de l'objet défini par vous ou saisi par le client.

xs:string

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

Guide de référence de l'API SOAP Mai 2007 87

API GetTransactionDetails

GetTransactionDetailsResponse

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

T ype de données et valeurs possibles

Number 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 example, item_number1, item_number2, etc.

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

Quantity Quantité définie par vous ou saisie par le client.

Nombre de caractères limite : pas de limite.

Amount Coût de l'objet. ebl:BasicAmount

Options

Options des objets PayPal pour le Panier.

Subscription Contient les éléments ci-après. ebl:Subscripti

SubscriptionID Numéro généré par PayPal pour l'abonné.

Nombre de caractères limite : pas de limite.

xs:string

transaction

ns:OptionType name :

xs:string value :

xs:string

on InfoType

xs:string

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 alphanumériques d'un octet.

88 Mai 2007 Guide de référence de l'API SOAP

xs:dateTime

xs:string

ABLEAU 5.2 Champs de GetTransactionDeta ilsRespon se (suite)

Champ Elément inclus Description

API GetTransactionDetails

GetTransactionDetailsResponse

T ype de données et valeurs possibles

Recurrences Le nombre de versements qui auront lieu au tarif

xs:string

standard. Nombre de caractères limite : pas de limite.

reattempt Indique si de nouvelles tentatives doivent être

xs:string

effectuées en cas d'échec de paiement.

recurring Indique s'il y a une base récurrente de facturation.

xs:string

1 = Oui

Subscription TermsType

Amount Montant qui sera débité à l'abonné en un seul

paiement.

eb:BasicAmount transaction

Nombre de caractères limite : pas de limite.

period Durée sur laquelle l'abonné sera débité.

xs:string

Nombre de caractères limite : pas de limite.

Auction Contient les éléments ci-après. ebl:Auction

Info Type

BuyerID Identification d'enchère du client. xs:string ClosingDate Date de clôture des enchères. xs:string multiItem

Compteur utilisé pour les paiements pour enchères de plusieurs objets.

xs:string

Guide de référence de l'API SOAP Mai 2007 89

API GetTransactionDetails

GetTransactionDetailsResponse

90 Mai 2007 Guide de référence de l'API SOAP

API MassPay

L'API MassPay est l'équivalent par programmation de la fonction Paiement groupé disponible sur le site de PayPal. Vous pouvez inclure jusqu'à 250 paiements par MassPayRequest. Vous devez avoir un solde PayPal dans chaque devise dans laquelle vous souhaitez effectuer un paiement et disposer d'une provision suffisante pour couvrir le montant et les frais des paiements groupés. Vous ne pouvez pas mélanger des devises dans la même requête MassPayRequest ; vous devez utiliser une requête différente pour chaque devise.

Le report des transactions de paiements sur des comptes de destinataire individuels n'est pas pris en charge par l'API Paiements groupés, mais par un processus PayPal distinct.

Notification instantanée de paiement

L'API MassPay déclenche l'envoi d'un email de notification instantanée de paiement au destinataire des fonds. Vous de vez consulter le NIP pour obtenir les informations nécessaires sur la transaction.

Schéma des types de MassPay

Le schéma suivant représente la composition des éléments de MassPayRequestType, MassPayRequestItemType et MassPayResponseT ype.

Guide de référence de l'API SOAP Mai 2007 91

API MassPay

MassPayRequest

FIGURE 6.1 Types de MassPay

MassPayRequest

Traite les paiements en masse pour 250 destinataires différents au maximum.

Champs

TABLEAU 6.1 Champs de Mas sPayReque stType

Champ Description Type de données

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.

ReceiverType Indique comment identifier les

destinataires des paiements pour tous les éléments MassPayItem : à l'aide de

EmailAddress (ReceiverEmail dans MassPayItem) ou de UserID (ReceiverID dans MassPayItem).

xs:string Voir la description. Non

ebl:ReceiverInfo CodeType xs:token

Valeurs possibles Obligatoire ?

Reportez-vous à la section

Non

Tableau 6.2.

92 Mai 2007 Guide de référence de l'API SOAP

ABLEAU 6.1 Champs de MassPayReque stType (suite)

Champ Description Type de données

API MassPay

MassPayRequest

Valeurs possibles Obligatoire ?

MassPayItem Détails de chaque paiement.

REMARQUE : une requête

MassPayRequest peut contenir

ebl:MassPay Item Type

jusqu'à 250 éléments MassPayItem.

ABLEAU 6.2 Enumération d e ReceiverInfoCod eType

Champ Description Obligatoire ?

EmailAddress Adresse email du destinataire enregistrée

Non

chez PayPal. Nombre de caractères limite : 12 caractères

alphanumériques d'un octet.

UserID Numéro de compte unique du client

Non

PayPal. Nombre de caractères limite : 6 caractères

d'un octet au maximum.

ABLEAU 6.3 Champs de MassPayItemType

Champ Description T ype de données

ReceiverEmail Adresse email du destinataire.

IMPORTANT : vous devez indiquer

ReceiverEmail ou ReceiverID,

ebl:Email Address Type

mais vous ne devez pas associer ReceiverEmail et ReceiverID dans le groupe des éléments MassPayItems. 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 au maximum.

Reportez-vous à la

Oui

section

Tableau 6.3.

Valeurs possibles Obligatoire ?

Voir la description. Non

Guide de référence de l'API SOAP Mai 2007 93

API MassPay

MassPayRequest

ABLEAU 6.3 Champs de MassPayItemType (suite)

Champ Description T ype de données

Valeurs possibles Obligatoire ?

ReceiverID Numéro de compte unique du client

PayPal. Cette valeur correspond à la valeur de PayerID renvoyée par GetTransactionDetails.

IMPORTANT : Vous devez indiquer

ReceiverEmail ou ReceiverID, mais vous ne devez pas associer ReceiverEmail et ReceiverID dans le groupe des éléments MassPayItems. Utilisez uniquement l'un ou l'autre, mais pas les deux, dans la même requête.

Nombre de caractères limite : 17 caractères d'un octet au maximum.

Amount Montant du paiement.

REMARQUE :

currencyID

vous devez définir l'attribut

sur l'un des codes des devises à trois caractères pour toutes les devises acceptées par PayPal. Reportezvous à la section

, « Codage de

caractères, types et formats des données et devises » page 24

xs:string Transaction-

Non

specific

ebl:Basic Amount

Transactionspecific

Oui

transaction

IMPORTANT : vous ne pouvez pas

mélanger des devises dans une requête MassPayRequest unique. Une requête unique doit contenir des objets appartenant à la même devise.

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

Note Remarque personnalisée pour chaque

destinataire. Nombre de caractères limite :

4 000 caractères alphanumériques d'un octet

xs:string Transaction-

specific

xs:string Transaction-

specific

Non

94 Mai 2007 Guide de référence de l'API SOAP

MassPayResponse

Réponse à MassPayRequest.

Champs

Les éléments renvoyés sont identiques à ceux de AbstractResponseType. Reportez-vous à la section « AbstractResponseType » page 30.

Pour les codes et les messages d'erreur et leur signification, reportez-vous à l'Annexe A, « Code s et messages d'erreur de toutes les API PayPal » .

API MassPay

MassPayResponse

Guide de référence de l'API SOAP Mai 2007 95

API MassPay

MassPayResponse

96 Mai 2007 Guide de référence de l'API SOAP

API RefundTransaction

Utilisez l'API RefundTransaction pour effectuer des remboursements complets ou partiels.

Schéma des types de RefundTransaction

Le schéma suivant représente la composition des éléments de RefundTransactionRequestType et RefundTransac tionResponseType.

FIGURE 7.1 Types de RefundTransaction

RefundTransactionRequest

Demande de remboursement d'un paiement. Avec RefundTransactionRequest, vous devez toujours transmettre les valeurs de

TransactionID et RefundType. Si RefundType est défini sur Full, vous ne devez pas définir Amount ; cependant, si RefundType est défini sur Partial, vous devez définir Amount.

Guide de référence de l'API SOAP Mai 2007 97

API RefundTransaction

RefundTransactionResponse

Champs

TABLEAU 7.1 Champs de Refun dTransactionReques t

Champ Description T ype de données

Valeurs possibles Obligatoire ?

TransactionID Identifiant unique d'une transaction.

Nombre de caractères limite : 17 uméro caractères d'un octet.

RefundType Type de remboursement effectué.

z None z Fu ll z Pa rtial

Amount Montant du remboursement.

Edoit être défini si RefundType is Partial.

REMARQUE : si RefundType a la

valeur Full, ne définissez pas

Amount

Memo Mémo personnalisé concernant le

remboursement. Nombre de caractères limite : 255

caractères alphanumériques d'un octet.

xs:string Transaction-

specific

ebl:RefundPurp oseTypeCode Type

xs:token ebl:Basic

Amount transaction

xs:string Transaction-

None Full Partial

Transactionspecific

specific

Oui

Voir la description

Non

RefundTransactionResponse

Réponse à RefundTransactionRequest.

Champs

ABLEAU 7.2 Champs de RefundTransactionResp onse

Champ Description Ty pe de données Valeur

Refund Transaction ID

98 Mai 2007 Guide de référence de l'API SOAP

Numéro de transaction unique du remboursement. Nombre de caractères limite : 17 numéro caractères

d'un octet.

xs:string Voir la description.

API RefundTransaction

RefundTransactionResponse

ABLEAU 7.2 Champs de RefundTransactionResp onse (s uite)

Champ Description Ty pe de données Valeur

FeeRefund Amount

GrossRefund Amount

NetRefund Amount

Commission sur transaction remboursée au destinataire initial du paiement.

ebl:BasicAmount transaction

Somme d'argent remboursée au payeur initial. ebl:BasicAmount

transaction

Montant soustrait du solde PayPal du destinataire initial du paiement pour effectuer ce

ebl:BasicAmount transaction

remboursement.

Voir la descripti on.

Guide de référence de l'API SOAP Mai 2007 99

API RefundTransaction

RefundTransactionResponse

100 Mai 2007 Guide de référence de l'API SOAP

PAYPAL API Soap - 2007 Guide de référence [fr]

Specifications and Main Features

Frequently Asked Questions

User Manual

Préface

A propos de ce document

Public ciblé

Conventions typographiques

Problèmes relatifs à la documentation

Historique des révisions

Architecture des services

Définitions du schéma WSDL/XSD PayPal

Concepts et terminologie API

Sécurité

Nœuds de service SOAP

Implémentation SOAP

Style de message SOAP : doc-literal

Structure d'une requête SOAP

Structure d'une requête

Structure de la réponse

Réponses aux erreurs

Définitions de l'API SOAP de PayPal

CorrelationID pour signaler des problèmes à PayPal

Codage de caractères, types et formats des données et devises

API par fonction de gestion

API pour échanger des fonds ou afficher des informations

Notification instantanée de paiement et API

Schéma des principaux types eBL

AbstractRequestType

Champs

AbstractResponseType

Champs

API Autorisation et collecte

DoCapture

Schéma des types de DoCapture

DoCaptureRequest

DoCaptureResponse

DoAuthorization

Schéma des types de DoAuthorization

DoAuthorizationRequest

DoAuthorizationResponse

DoVoid

Schéma des types de DoVoid

DoVoidRequest

DoVoidResponse

DoReauthorization

Schéma des types de DoReauthorization

DoReauthorizationRequest

DoReauthorizationResponse

API Paiement express PayPal

Paiement express PayPal pour les enchères eBay

SetExpressCheckout

Schéma des types de Set ExpressCheckout

SetExpressCheckoutRequest

GetExpressCheckoutDetails

SetExpressCheckoutResponse

Schéma des types de GetExpressCheckoutDetails

GetExpressCheckoutDetailsRequest

GetExpressCheckoutDetailsResponse

DoExpressCheckoutPayment

Schéma des types de DoExpressCheckoutPayment

DoExpressCheckoutPaymentRequest

DoExpressCheckoutPaymentResponse

API GetTransactionDetails

Schéma des types de GetTransactionDetails

GetTransactionDetailsRequest

Champs

GetTransactionDetailsResponse

Champs

API MassPay

Notification instantanée de paiement

Schéma des types de MassPay

MassPayRequest

Champs

MassPayResponse

Champs

API RefundTransaction

Schéma des types de RefundTransaction

RefundTransactionRequest

RefundTransactionResponse