1Business::PayPal::API(3U)ser Contributed Perl DocumentatiBounsiness::PayPal::API(3)
2
6 Business::PayPal::API - PayPal SOAP API client with sandbox support
7
9 version 0.77
10
12 use Business::PayPal::API qw( ExpressCheckout GetTransactionDetails );
13 ## 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 ## 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 ## 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 my %response = $pp->SetExpressCheckout( ... );
42
44 Business::PayPal::API supports both certificate authentication and the
45 new 3-token "Signature" authentication.
46 It also supports PayPal's development sandbox for testing. See the
48 sandbox parameter to new() below for details.
49 Business::PayPal::API can import other API derived classes:
51 use Business::PayPal::API qw( RefundTransaction );
53 This allows for much more concise and intuitive usage. For example,
55 these two statements are equivalent:
56 use Business::PayPal::API::RefundTransaction;
58 my $pp = Business::PayPal::API::RefundTransaction->new( ... );
59 $pp->RefundTransaction( ... );
60 and more concisely:
62 use Business::PayPal::API qw( RefundTransaction );
64 my $pp = Business::PayPal::API->new( ... );
65 $pp->RefundTransaction( ... );
66 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 use Business::PayPal::API qw( GetTransactionDetails
74 TransactionSearch
75 RefundTransaction );
76 my $pp = Business::PayPal::API->new( ... );
77 my $records = $pp->TransactionSearch( ... );
78 my %details = $pp->GetTransactionDetails( ... );
80 my %resp = $pp->RefundTransaction( ... );
82 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 For details on Business::PayPal::API::* subclasses, see each subclass's
87 individual documentation.
88 new
90 Creates a new Business::PayPal::API object.
91 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 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 My Account -> Profile -> API Access -> Request API Credentials
103 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 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 Subject
115 Optional. This is used by PayPal to authenticate 3rd party billers
116 using your account. See the documents in "SEE ALSO".
117 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 PKCS12File
124 Required for PKCS#12 certificate authentication, unless the
125 HTTPS_PKCS12_FILE environment variable is already set.
126 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 PKCS12Password
133 Required for PKCS#12 certificate authentication, unless the
134 HTTPS_PKCS12_PASSWORD environment variable is already set.
135 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 CertFile
142 Required for PEM certificate authentication, unless the
143 HTTPS_CERT_FILE environment variable is already set.
144 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 You may combine both certificate and private key into one file and
152 set CertFile and KeyFile to the same path.
153 KeyFile
155 Required for PEM certificate authentication, unless the
156 HTTPS_KEY_FILE environment variable is already set.
157 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 You may combine both certificate and private key into one file and
165 set CertFile and KeyFile to the same path.
166 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 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 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 PayPal's sandbox reference:
184 <https://www.paypal.com/IntegrationCenter/ic_sandbox.html>
186 proxy_url
188 Optional. When set, the proxy at the specified URL will be used for
189 outbound connections.
190 timeout
192 Optional. Set the timeout in seconds. Defaults to 30 seconds.
193
195 Business::PayPal::API - PayPal API
196
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 [ { ErrorCode => 10002,
204 LongMessage => "Invalid security header" },
205 { ErrorCode => 10030,
207 LongMessage => "Some other error" }, ]
208 You can retrieve these errors like this:
210 %response = $pp->doSomeAPICall();
212 if( $response{Ack} ne 'Success' ) {
213 for my $err ( @{$response{Errors}} ) {
214 warn "Error: " . $err->{LongMessage} . "\n";
215 }
216 }
217
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 The format for this file is as follows:
226 Username = your_api.username.com
228 Password = your_api_password
229 and then ONE of the following options:
231 a) supply 3-token authentication signature
233 Signature = xxxxxxxxxxxxxxxxxxxxxxxx
235 b) supply PEM certificate credentials
237 CertFile = /path/to/cert_key_pem.txt
239 KeyFile = /path/to/cert_key_pem.txt
240 c) supply PKCS#12 certificate credentials
242 PKCS12File = /path/to/cert.p12
244 PKCS12Password = pkcs12_password
245 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 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 See 'auth.sample.*' files in this package for an example of the file
254 format. Variables are case-*sensitive*.
255 Any of the following variables are recognized:
257 Username Password Signature Subject
259 CertFile KeyFile PKCS12File PKCS12Password
260 BuyerEmail
261 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
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 * 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 * you're not trying to use your live username and password for
279 sandbox testing and vice versa.
280 * you are using a US Business Sandbox account, you may also need to have
282 "PayPal Payments Pro" enabled.
283 * 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 * if you use certificate authentication, your certificate must be
290 the correct one (live or sandbox) depending on what you're doing.
291 * 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 Try clearing your environment:
300 ## delete all HTTPS, SSL env
302 delete $ENV{$_} for grep { /^(HTTPS|SSL)/ } keys %ENV;
303 ## now put our own HTTPS env back in
305 $ENV{HTTPS_CERT_FILE} = '/var/path/to/cert.pem';
306 ## create our paypal object
308 my $pp = Business::PayPal::API->new(...)
309 * 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 local $IO::Socket::SSL::VERSION = undef;
317 $pp->DoExpressCheckoutPayment(...);
319 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 * 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 See the DEBUGGING section below for further hints.
331 PayPal Munging URLs
333 PayPal seems to be munging my URLs when it returns.
334 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 '&' and '<' on the way
338 back, so if you have an ampersand in your ReturnURL (for example), your
339 customers will be redirected here:
340 http://domain.tld/prog?arg1=foo&arg2=bar
342 instead of here:
344 http://domain.tld/prog?arg1=foo&arg2=bar
346 Solution:
348 Use CDATA tags to wrap your request:
350 ReturnURL => '<![CDATA[http://domain.tld/prog?arg1=foo&arg2=bar]]>'
352 You may also use semicolons instead of ampersands to separate your URL
354 arguments:
355 ReturnURL => 'http://domain.tld/prog?arg1=foo;arg2=bar'
357 (thanks to Ollie Ready)
359
361 You can see the raw SOAP XML sent and received by Business::PayPal::API
362 by setting its $Debug variable:
363 $Business::PayPal::API::Debug = 1;
365 $pp->SetExpressCheckout( %args );
366 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 If anyone knows how to turn a SOAP::SOM object into XML without setting
372 outputxml(), let me know.
373
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 But in a nutshell:
381 package Business::PayPal::API::SomeAPI;
383 use 5.008001;
385 use strict;
386 use warnings;
387 use SOAP::Lite 0.67;
389 use Business::PayPal::API ();
390 our @ISA = qw(Business::PayPal::API);
392 our @EXPORT_OK = qw( SomeAPIMethod );
393 sub SomeAPIMethod {
395 ...
396 }
397 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 use Business::PayPal::API qw( SomeAPI );
404 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 use Business::PayPal::API qw( SomeAPI );
409 my $pp = Business::PayPal::API->new( ... );
410 $pp->SomeAPIMethod( ... );
411 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 use Business::PayPal::API::SomeAPI;
416 my $pp = Business::PayPal::API::SomeAPI->new( ... ); ## same args as superclass
417 $pp->SomeAPIMethod( ... );
418 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
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
429 None by default.
430
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 (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 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 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
455 Wherein I acknowledge all the good folks who have contributed to this
456 module in some way:
457 • Daniel P. Hembree
459 for authoring the AuthorizationRequest, CaptureRequest,
461 DirectPayments, ReauthorizationRequest, and VoidRequest extensions.
462 • <jshiles at base16consulting daught com>
464 for finding some API typos in the ExpressCheckout API
466 • Andy Spiegl <paypalcheckout.Spiegl@kascada.com>
468 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 • Ollie Ready <oready at drjays daught com>
474 for the heads-up on the newest 3-token auth URI as well as a pile
476 of documentation inconsistencies.
477 • Michael Hendricks <michael at ndrix daught org>
479 for a patch that adds ShippingTotal to the DirectPayments module.
481 • Erik Aronesty, Drew Simpson via rt.cpan.org (#28596)
483 for a patch to fix getFields() when multiple items are returned
485 • Sebastian Böhm via email, SDC via rt.cpan.org (#38915)
487 for a heads-up that the PayPal documentation for MassPay API was
489 wrong regarding the UniqueId parameter.
490 • Jonathon Wright via email
492 for patches for ExpressCheckout and RecurringPayments that
494 implement BillingAgreement and DoReferenceTransaction API calls.
495
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
503 • Scott Wiersdorf <scott@perlcode.org>
504 • Danny Hembree <danny@dynamical.org>
506 • 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 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.
515perl v5.38.0 2023-07-20 Business::PayPal::API(3)