1Business::PayPal::API(3U)ser Contributed Perl DocumentatiBounsiness::PayPal::API(3)
2
3
4

NAME

6       Business::PayPal::API - PayPal SOAP API client with sandbox support
7

VERSION

9       version 0.77
10

SYNOPSIS

12           use Business::PayPal::API qw( ExpressCheckout GetTransactionDetails );
13
14           ## certificate authentication
15           my $pp = Business::PayPal::API->new(
16               Username       => 'my_api1.domain.tld',
17               Password       => 'this_is_my_password',
18               PKCS12File     => '/path/to/cert.pkcs12',
19               PKCS12Password => '(pkcs12 password)',
20               sandbox        => 1,
21           );
22
23           ## PEM cert authentication
24           my $pp = Business::PayPal::API->new(
25               Username => 'my_api1.domain.tld',
26               Password => 'this_is_my_password',
27               CertFile => '/path/to/cert.pem',
28               KeyFile  => '/path/to/cert.pem',
29               sandbox  => 1,
30           );
31
32           ## 3-token (Signature) authentication
33           my $pp = Business::PayPal::API->new(
34               Username => 'my_api1.domain.tld',
35               Password => 'Xdkis9k3jDFk39fj29sD9',    ## supplied by PayPal
36               Signature =>
37                   'f7d03YCpEjIF3s9Dk23F2V1C1vbYYR3ALqc7jm0UrCcYm-3ksdiDwjfSeii', ## ditto
38               sandbox => 1,
39           );
40
41           my %response = $pp->SetExpressCheckout( ... );
42

DESCRIPTION

44       Business::PayPal::API supports both certificate authentication and the
45       new 3-token "Signature" authentication.
46
47       It also supports PayPal's development sandbox for testing. See the
48       sandbox parameter to new() below for details.
49
50       Business::PayPal::API can import other API derived classes:
51
52         use Business::PayPal::API qw( RefundTransaction );
53
54       This allows for much more concise and intuitive usage. For example,
55       these two statements are equivalent:
56
57         use Business::PayPal::API::RefundTransaction;
58         my $pp = Business::PayPal::API::RefundTransaction->new( ... );
59         $pp->RefundTransaction( ... );
60
61       and more concisely:
62
63         use Business::PayPal::API qw( RefundTransaction );
64         my $pp = Business::PayPal::API->new( ... );
65         $pp->RefundTransaction( ... );
66
67       The advantage of this becomes clear when you need to use multiple API
68       calls in your program; this allows you to use the same object to invoke
69       the various methods, instead of creating a new object for each
70       subclass. Here is an example of a API object used to invoke various
71       PayPal APIs with the same object:
72
73         use Business::PayPal::API qw( GetTransactionDetails
74                                       TransactionSearch
75                                       RefundTransaction );
76         my $pp = Business::PayPal::API->new( ... );
77         my $records = $pp->TransactionSearch( ... );
78
79         my %details = $pp->GetTransactionDetails( ... );
80
81         my %resp = $pp->RefundTransaction( ... );
82
83       However, you may certainly use just the subclass if that's all you
84       need. Every subclass should work as its own self-contained API.
85
86       For details on Business::PayPal::API::* subclasses, see each subclass's
87       individual documentation.
88
89   new
90       Creates a new Business::PayPal::API object.
91
92       A note about certificate authentication: PayPal (and this module)
93       support either PKCS#12 certificate authentication or PEM certificate
94       authentication. See options below.
95
96       Username
97           Required. This is the PayPal API username, usually in the form of
98           'my_api1.mydomain.tld'. You can find or create your API credentials
99           by logging into PayPal (if you want to do testing, as you should,
100           you should also create a developer sandbox account) and going to:
101
102             My Account -> Profile -> API Access -> Request API Credentials
103
104           Please see the PayPal API Reference and PayPal Sandbox User Guide
105           for details on creating a PayPal business account and sandbox
106           account for testing.
107
108       Password
109           Required. If you use certificate authentication, this is the PayPal
110           API password created when you setup your certificate. If you use
111           3-token (Signature) authentication, this is the password PayPal
112           assigned you, along with the "API User Name" and "Signature Hash".
113
114       Subject
115           Optional. This is used by PayPal to authenticate 3rd party billers
116           using your account. See the documents in "SEE ALSO".
117
118       Signature
119           Required for 3-token (Signature) authentication. This is the
120           "Signature Hash" you received when you did "Request API
121           Credentials" in your PayPal Business Account.
122
123       PKCS12File
124           Required for PKCS#12 certificate authentication, unless the
125           HTTPS_PKCS12_FILE environment variable is already set.
126
127           This contains the path to your private key for PayPal
128           authentication. It is used to set the HTTPS_PKCS12_FILE environment
129           variable. You may set this environment variable yourself and leave
130           this field blank.
131
132       PKCS12Password
133           Required for PKCS#12 certificate authentication, unless the
134           HTTPS_PKCS12_PASSWORD environment variable is already set.
135
136           This contains the PKCS#12 password for the key specified in
137           PKCS12File. It is used to set the HTTPS_PKCS12_PASSWORD environment
138           variable. You may set this environment variable yourself and leave
139           this field blank.
140
141       CertFile
142           Required for PEM certificate authentication, unless the
143           HTTPS_CERT_FILE environment variable is already set.
144
145           This contains the path to your PEM format certificate given to you
146           from PayPal (and accessible in the same location that your Username
147           and Password and/or Signature Hash are found) and is used to set
148           the HTTPS_CERT_FILE environment variable. You may set this
149           environment variable yourself and leave this field blank.
150
151           You may combine both certificate and private key into one file and
152           set CertFile and KeyFile to the same path.
153
154       KeyFile
155           Required for PEM certificate authentication, unless the
156           HTTPS_KEY_FILE environment variable is already set.
157
158           This contains the path to your PEM format private key given to you
159           from PayPal (and accessible in the same location that your Username
160           and Password and/or Signature Hash are found) and is used to set
161           the HTTPS_KEY_FILE environment variable. You may set this
162           environment variable yourself and leave this field blank.
163
164           You may combine both certificate and private key into one file and
165           set CertFile and KeyFile to the same path.
166
167       sandbox
168           Required. If set to true (default), Business::PayPal::API will
169           connect to PayPal's development sandbox, instead of PayPal's live
170           site. *You must explicitly set this to false (0) to access PayPal's
171           live site*.
172
173           If you use PayPal's development sandbox for testing, you must have
174           already signed up as a PayPal developer and created a Business
175           sandbox account and a Buyer sandbox account (and make sure both of
176           them have Verified status in the sandbox).
177
178           When testing with the sandbox, you will use different usernames,
179           passwords, and certificates (if using certificate authentication)
180           than you will when accessing PayPal's live site. Please see the
181           PayPal documentation for details. See "SEE ALSO" for references.
182
183           PayPal's sandbox reference:
184
185           <https://www.paypal.com/IntegrationCenter/ic_sandbox.html>
186
187       proxy_url
188           Optional. When set, the proxy at the specified URL will be used for
189           outbound connections.
190
191       timeout
192           Optional. Set the timeout in seconds. Defaults to 30 seconds.
193

NAME

195       Business::PayPal::API - PayPal API
196

ERROR HANDLING

198       Every API call should return an Ack response, whether Success, Failure,
199       or otherwise (depending on the API call). If it returns any non-success
200       value, you can find an Errors entry in your return hash, whose value is
201       an arrayref of hashrefs:
202
203        [ { ErrorCode => 10002,
204            LongMessage => "Invalid security header" },
205
206          { ErrorCode => 10030,
207            LongMessage => "Some other error" }, ]
208
209       You can retrieve these errors like this:
210
211         %response = $pp->doSomeAPICall();
212         if( $response{Ack} ne 'Success' ) {
213             for my $err ( @{$response{Errors}} ) {
214                 warn "Error: " . $err->{LongMessage} . "\n";
215             }
216         }
217

TESTING

219       Testing the Business::PayPal::API::* modules requires that you create a
220       file containing your PayPal Developer Sandbox authentication
221       credentials (e.g., API certificate authentication or 3-Token
222       authentication signature, etc.) and setting the WPP_TEST environment
223       variable to point to this file.
224
225       The format for this file is as follows:
226
227         Username = your_api.username.com
228         Password = your_api_password
229
230       and then ONE of the following options:
231
232         a) supply 3-token authentication signature
233
234             Signature = xxxxxxxxxxxxxxxxxxxxxxxx
235
236         b) supply PEM certificate credentials
237
238             CertFile = /path/to/cert_key_pem.txt
239             KeyFile  = /path/to/cert_key_pem.txt
240
241         c) supply PKCS#12 certificate credentials
242
243             PKCS12File = /path/to/cert.p12
244             PKCS12Password = pkcs12_password
245
246       You may also set the appropriate HTTPS_* environment variables for b)
247       and c) above (e.g., HTTPS_CERT_FILE, HTTPS_KEY_FILE, HTTPS_PKCS12_File,
248       HTTPS_PKCS12_PASSWORD) in lieu of putting this information in a file.
249
250       Then use "WPP_TEST=my_auth.txt make test" (for Bourne shell derivates)
251       or "setenv WPP_TEST my_auth.txt && make test" (for C-shell derivates).
252
253       See 'auth.sample.*' files in this package for an example of the file
254       format. Variables are case-*sensitive*.
255
256       Any of the following variables are recognized:
257
258         Username Password Signature Subject
259         CertFile KeyFile PKCS12File PKCS12Password
260         BuyerEmail
261
262       Note: PayPal authentication may fail if you set the certificate
263       environment variables and attempt to connect using 3-token
264       authentication (i.e., PayPal will use the first authentication
265       credentials presented to it, and if they fail, the connection is
266       aborted).
267

TROUBLESHOOTING

269   PayPal Authentication Errors
270       If you are experiencing PayPal authentication errors (e.g., "Security
271       header is not valid", "SSL negotiation failed", etc.), you should make
272       sure:
273
274          * your username and password match those found in your PayPal
275            Business account sandbox (this is not the same as your regular
276            account).
277
278          * you're not trying to use your live username and password for
279            sandbox testing and vice versa.
280
281          * you are using a US Business Sandbox account, you may also need to have
282            "PayPal Payments Pro" enabled.
283
284          * if the sandbox works but "live" does not, make sure you've turned
285            off the 'sandbox' parameter correctly. Otherwise you'll be
286            passing your PayPal sandbox credentials to PayPal's live site
287            (which won't work).
288
289          * if you use certificate authentication, your certificate must be
290            the correct one (live or sandbox) depending on what you're doing.
291
292          * if you use 3-Token authentication (i.e., Signature), you don't
293            have any B<PKCS12*> parameters or B<CertFile> or B<KeyFile>
294            parameters in your constructor AND that none of the corresponding
295            B<HTTPS_*> environment variables are set. PayPal prefers
296            certificate authentication since it occurs at connection time; if
297            it fails, it will not try Signature authentication.
298
299            Try clearing your environment:
300
301                ## delete all HTTPS, SSL env
302                delete $ENV{$_} for grep { /^(HTTPS|SSL)/ } keys %ENV;
303
304                ## now put our own HTTPS env back in
305                $ENV{HTTPS_CERT_FILE} = '/var/path/to/cert.pem';
306
307                ## create our paypal object
308                my $pp = Business::PayPal::API->new(...)
309
310          * if you have already loaded Net::SSLeay (or IO::Socket::SSL), then
311            Net::HTTPS will prefer to use IO::Socket::SSL. I don't know how
312            to get SOAP::Lite to work with IO::Socket::SSL (e.g.,
313            Crypt::SSLeay uses HTTPS_* environment variables), so until then,
314            you can use this hack:
315
316              local $IO::Socket::SSL::VERSION = undef;
317
318              $pp->DoExpressCheckoutPayment(...);
319
320            This will tell Net::HTTPS to ignore the fact that IO::Socket::SSL
321            is already loaded for this scope and import Net::SSL (part of the
322            Crypt::SSLeay package) for its 'configure()' method.
323
324          * if you receive a message like "500 Can't connect to
325            api.sandbox.paypal.com:443 (Illegal seek)", you'll need to make
326            sure you have Crypt::SSLeay installed. It seems that other crypto
327            modules don't do the certificate authentication quite as well,
328            and LWP needs this to negotiate the SSL connection with PayPal.
329
330       See the DEBUGGING section below for further hints.
331
332   PayPal Munging URLs
333       PayPal seems to be munging my URLs when it returns.
334
335       SOAP::Lite follows the XML specification carefully, and encodes '&' and
336       '<' characters before applying them to the SOAP document. PayPal does
337       not properly URL-decode HTML entities '&amp;' and '&lt;' on the way
338       back, so if you have an ampersand in your ReturnURL (for example), your
339       customers will be redirected here:
340
341         http://domain.tld/prog?arg1=foo&amp;arg2=bar
342
343       instead of here:
344
345         http://domain.tld/prog?arg1=foo&arg2=bar
346
347       Solution:
348
349       Use CDATA tags to wrap your request:
350
351         ReturnURL => '<![CDATA[http://domain.tld/prog?arg1=foo&arg2=bar]]>'
352
353       You may also use semicolons instead of ampersands to separate your URL
354       arguments:
355
356         ReturnURL => 'http://domain.tld/prog?arg1=foo;arg2=bar'
357
358       (thanks to Ollie Ready)
359

DEBUGGING

361       You can see the raw SOAP XML sent and received by Business::PayPal::API
362       by setting its $Debug variable:
363
364         $Business::PayPal::API::Debug = 1;
365         $pp->SetExpressCheckout( %args );
366
367       this will print the XML being sent, and dump a Perl data structure of
368       the SOM received on STDERR (so check your error_log if running inside a
369       web server).
370
371       If anyone knows how to turn a SOAP::SOM object into XML without setting
372       outputxml(), let me know.
373

DEVELOPMENT

375       If you are a developer wanting to extend Business::PayPal::API for
376       other PayPal API calls, you can review any of the included modules
377       (e.g., RefundTransaction.pm or ExpressCheckout.pm) for examples on how
378       to do this until I have more time to write a more complete document.
379
380       But in a nutshell:
381
382         package Business::PayPal::API::SomeAPI;
383
384         use 5.008001;
385         use strict;
386         use warnings;
387
388         use SOAP::Lite 0.67;
389         use Business::PayPal::API ();
390
391         our @ISA = qw(Business::PayPal::API);
392         our @EXPORT_OK = qw( SomeAPIMethod );
393
394         sub SomeAPIMethod {
395          ...
396         }
397
398       Notice the @EXPORT_OK variable. This is not used by Exporter (we don't
399       load Exporter at all): it is a special variable used by
400       Business::PayPal::API to know which methods to import when
401       Business::PayPal::API is run like this:
402
403         use Business::PayPal::API qw( SomeAPI );
404
405       That is, Business::PayPal::API will import any subroutine into its own
406       namespace from the @EXPORT_OK array. Now it can be used like this:
407
408         use Business::PayPal::API qw( SomeAPI );
409         my $pp = Business::PayPal::API->new( ... );
410         $pp->SomeAPIMethod( ... );
411
412       Of course, we also do a 'use Business::PayPal::API' in the module so
413       that it can be used as a standalone module, if necessary:
414
415         use Business::PayPal::API::SomeAPI;
416         my $pp = Business::PayPal::API::SomeAPI->new( ... ); ## same args as superclass
417         $pp->SomeAPIMethod( ... );
418
419       Adding the @EXPORT_OK array in your module allows your module to be
420       used in the most convenient way for the given circumstances.
421

EXAMPLES

423       Andy Spiegl <paypalcheckout.Spiegl@kascada.com> has kindly donated some
424       example code (in German) for the ExpressCheckout API which may be found
425       in the eg directory of this archive. Additional code examples for other
426       APIs may be found in the t test directory.
427

EXPORT

429       None by default.
430

CAVEATS

432       Because I haven't figured out how to make SOAP::Lite read the WSDL
433       definitions directly and simply implement those (help, anyone?), I have
434       essentially recreated all of those WSDL structures internally in this
435       module.
436
437       (Note - 6 Oct 2006: SOAP::Lite's WSDL support is moving ahead, but
438       slowly. The methods used by this API are considered "best practice" and
439       are safe to use).
440
441       As with all web services, if PayPal stop supporting their API endpoint,
442       this module *may stop working*. You can help me keep this module up-to-
443       date if you notice such an event occurring.
444
445       Also, I didn't implement a big fat class hierarchy to make this module
446       "academically" correct. You'll notice that I fudged colliding parameter
447       names in DoExpressCheckoutPayment and similar fudging may be found in
448       GetTransactionDetails. The good news is that this was written quickly,
449       works, and is dead-simple to use. The bad news is that this sort of
450       collision might occur again as more and more data is sent in the API
451       (call it 'eBay API bloat'). I'm willing to take the risk this will be
452       rare (PayPal--please make it rare!).
453

ACKNOWLEDGEMENTS

455       Wherein I acknowledge all the good folks who have contributed to this
456       module in some way:
457
458       •   Daniel P. Hembree
459
460           for authoring the AuthorizationRequest, CaptureRequest,
461           DirectPayments, ReauthorizationRequest, and VoidRequest extensions.
462
463       •   <jshiles at base16consulting daught com>
464
465           for finding some API typos in the ExpressCheckout API
466
467       •   Andy Spiegl <paypalcheckout.Spiegl@kascada.com>
468
469           for giving me the heads-up on PayPal's new 3-token auth URI and for
470           a sample command-line program (found in the 'eg' directory)
471           demonstrating the ExpressCheckout API.
472
473       •   Ollie Ready <oready at drjays daught com>
474
475           for the heads-up on the newest 3-token auth URI as well as a pile
476           of documentation inconsistencies.
477
478       •   Michael Hendricks <michael at ndrix daught org>
479
480           for a patch that adds ShippingTotal to the DirectPayments module.
481
482       •   Erik Aronesty, Drew Simpson via rt.cpan.org (#28596)
483
484           for a patch to fix getFields() when multiple items are returned
485
486       •   Sebastian Böhm via email, SDC via rt.cpan.org (#38915)
487
488           for a heads-up that the PayPal documentation for MassPay API was
489           wrong regarding the UniqueId parameter.
490
491       •   Jonathon Wright via email
492
493           for patches for ExpressCheckout and RecurringPayments that
494           implement BillingAgreement and DoReferenceTransaction API calls.
495

SEE ALSO

497       SOAP::Lite, PayPal User Guide
498       <https://developer.paypal.com/webapps/developer/docs/classic/products>,
499       PayPal API Reference
500       <https://developer.paypal.com/webapps/developer/docs/api/overview>
501

AUTHORS

503       •   Scott Wiersdorf <scott@perlcode.org>
504
505       •   Danny Hembree <danny@dynamical.org>
506
507       •   Bradley M. Kuhn <bkuhn@ebb.org>
508
510       This software is copyright (c) 2006-2017 by Scott Wiersdorf, Danny
511       Hembree, Bradley M. Kuhn.
512
513       This is free software; you can redistribute it and/or modify it under
514       the same terms as the Perl 5 programming language system itself.
515
516
517
518perl v5.34.0                      2021-07-22          Business::PayPal::API(3)
Impressum