.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Business::PayPal::API 3pm" .TH Business::PayPal::API 3pm "2022-08-28" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Business::PayPal::API \- PayPal SOAP API client with sandbox support .SH "VERSION" .IX Header "VERSION" version 0.77 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Business::PayPal::API qw( ExpressCheckout GetTransactionDetails ); \& \& ## certificate authentication \& my $pp = Business::PayPal::API\->new( \& Username => \*(Aqmy_api1.domain.tld\*(Aq, \& Password => \*(Aqthis_is_my_password\*(Aq, \& PKCS12File => \*(Aq/path/to/cert.pkcs12\*(Aq, \& PKCS12Password => \*(Aq(pkcs12 password)\*(Aq, \& sandbox => 1, \& ); \& \& ## PEM cert authentication \& my $pp = Business::PayPal::API\->new( \& Username => \*(Aqmy_api1.domain.tld\*(Aq, \& Password => \*(Aqthis_is_my_password\*(Aq, \& CertFile => \*(Aq/path/to/cert.pem\*(Aq, \& KeyFile => \*(Aq/path/to/cert.pem\*(Aq, \& sandbox => 1, \& ); \& \& ## 3\-token (Signature) authentication \& my $pp = Business::PayPal::API\->new( \& Username => \*(Aqmy_api1.domain.tld\*(Aq, \& Password => \*(AqXdkis9k3jDFk39fj29sD9\*(Aq, ## supplied by PayPal \& Signature => \& \*(Aqf7d03YCpEjIF3s9Dk23F2V1C1vbYYR3ALqc7jm0UrCcYm\-3ksdiDwjfSeii\*(Aq, ## ditto \& sandbox => 1, \& ); \& \& my %response = $pp\->SetExpressCheckout( ... ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBBusiness::PayPal::API\fR supports both certificate authentication and the new 3\-token \*(L"Signature\*(R" authentication. .PP It also supports PayPal's development \fIsandbox\fR for testing. See the \&\fBsandbox\fR parameter to \fB\fBnew()\fB\fR below for details. .PP \&\fBBusiness::PayPal::API\fR can import other \fB\s-1API\s0\fR derived classes: .PP .Vb 1 \& use Business::PayPal::API qw( RefundTransaction ); .Ve .PP This allows for much more concise and intuitive usage. For example, these two statements are equivalent: .PP .Vb 3 \& use Business::PayPal::API::RefundTransaction; \& my $pp = Business::PayPal::API::RefundTransaction\->new( ... ); \& $pp\->RefundTransaction( ... ); .Ve .PP and more concisely: .PP .Vb 3 \& use Business::PayPal::API qw( RefundTransaction ); \& my $pp = Business::PayPal::API\->new( ... ); \& $pp\->RefundTransaction( ... ); .Ve .PP The advantage of this becomes clear when you need to use multiple \s-1API\s0 calls in your program; this allows you to use the same object to invoke the various methods, instead of creating a new object for each subclass. Here is an example of a \fB\s-1API\s0\fR object used to invoke various PayPal APIs with the same object: .PP .Vb 5 \& use Business::PayPal::API qw( GetTransactionDetails \& TransactionSearch \& RefundTransaction ); \& my $pp = Business::PayPal::API\->new( ... ); \& my $records = $pp\->TransactionSearch( ... ); \& \& my %details = $pp\->GetTransactionDetails( ... ); \& \& my %resp = $pp\->RefundTransaction( ... ); .Ve .PP However, you may certainly use just the subclass if that's all you need. Every subclass should work as its own self-contained \s-1API.\s0 .PP For details on \fBBusiness::PayPal::API::*\fR subclasses, see each subclass's individual documentation. .SS "new" .IX Subsection "new" Creates a new \fBBusiness::PayPal::API\fR object. .PP A note about certificate authentication: PayPal (and this module) support either PKCS#12 certificate authentication or \s-1PEM\s0 certificate authentication. See options below. .IP "\fBUsername\fR" 4 .IX Item "Username" Required. This is the PayPal \s-1API\s0 username, usually in the form of \&'my_api1.mydomain.tld'. You can find or create your \s-1API\s0 credentials by logging into PayPal (if you want to do testing, as you should, you should also create a developer sandbox account) and going to: .Sp .Vb 1 \& My Account \-> Profile \-> API Access \-> Request API Credentials .Ve .Sp Please see the \fIPayPal \s-1API\s0 Reference\fR and \fIPayPal Sandbox User Guide\fR for details on creating a PayPal business account and sandbox account for testing. .IP "\fBPassword\fR" 4 .IX Item "Password" Required. If you use certificate authentication, this is the PayPal \&\s-1API\s0 password created when you setup your certificate. If you use 3\-token (Signature) authentication, this is the password PayPal assigned you, along with the \*(L"\s-1API\s0 User Name\*(R" and \*(L"Signature Hash\*(R". .IP "\fBSubject\fR" 4 .IX Item "Subject" Optional. This is used by PayPal to authenticate 3rd party billers using your account. See the documents in \*(L"\s-1SEE ALSO\*(R"\s0. .IP "\fBSignature\fR" 4 .IX Item "Signature" Required for 3\-token (Signature) authentication. This is the \&\*(L"Signature Hash\*(R" you received when you did \*(L"Request \s-1API\s0 Credentials\*(R" in your PayPal Business Account. .IP "\fBPKCS12File\fR" 4 .IX Item "PKCS12File" Required for PKCS#12 certificate authentication, unless the \&\fB\s-1HTTPS_PKCS12_FILE\s0\fR environment variable is already set. .Sp This contains the path to your private key for PayPal authentication. It is used to set the \fB\s-1HTTPS_PKCS12_FILE\s0\fR environment variable. You may set this environment variable yourself and leave this field blank. .IP "\fBPKCS12Password\fR" 4 .IX Item "PKCS12Password" Required for PKCS#12 certificate authentication, unless the \&\fB\s-1HTTPS_PKCS12_PASSWORD\s0\fR environment variable is already set. .Sp This contains the PKCS#12 password for the key specified in \&\fBPKCS12File\fR. It is used to set the \fB\s-1HTTPS_PKCS12_PASSWORD\s0\fR environment variable. You may set this environment variable yourself and leave this field blank. .IP "\fBCertFile\fR" 4 .IX Item "CertFile" Required for \s-1PEM\s0 certificate authentication, unless the \&\s-1HTTPS_CERT_FILE\s0 environment variable is already set. .Sp This contains the path to your \s-1PEM\s0 format certificate given to you from PayPal (and accessible in the same location that your Username and Password and/or Signature Hash are found) and is used to set the \&\fB\s-1HTTPS_CERT_FILE\s0\fR environment variable. You may set this environment variable yourself and leave this field blank. .Sp You may combine both certificate and private key into one file and set \&\fBCertFile\fR and \fBKeyFile\fR to the same path. .IP "\fBKeyFile\fR" 4 .IX Item "KeyFile" Required for \s-1PEM\s0 certificate authentication, unless the \s-1HTTPS_KEY_FILE\s0 environment variable is already set. .Sp This contains the path to your \s-1PEM\s0 format private key given to you from PayPal (and accessible in the same location that your Username and Password and/or Signature Hash are found) and is used to set the \&\fB\s-1HTTPS_KEY_FILE\s0\fR environment variable. You may set this environment variable yourself and leave this field blank. .Sp You may combine both certificate and private key into one file and set \&\fBCertFile\fR and \fBKeyFile\fR to the same path. .IP "\fBsandbox\fR" 4 .IX Item "sandbox" Required. If set to true (default), \fBBusiness::PayPal::API\fR will connect to PayPal's development sandbox, instead of PayPal's live site. *You must explicitly set this to false (0) to access PayPal's live site*. .Sp If you use PayPal's development sandbox for testing, you must have already signed up as a PayPal developer and created a Business sandbox account and a Buyer sandbox account (and make sure both of them have \&\fBVerified\fR status in the sandbox). .Sp When testing with the sandbox, you will use different usernames, passwords, and certificates (if using certificate authentication) than you will when accessing PayPal's live site. Please see the PayPal documentation for details. See \*(L"\s-1SEE ALSO\*(R"\s0 for references. .Sp PayPal's sandbox reference: .Sp .IP "\fBproxy_url\fR" 4 .IX Item "proxy_url" Optional. When set, the proxy at the specified \s-1URL\s0 will be used for outbound connections. .IP "\fBtimeout\fR" 4 .IX Item "timeout" Optional. Set the timeout in seconds. Defaults to 30 seconds. .SH "NAME" Business::PayPal::API \- PayPal API .SH "ERROR HANDLING" .IX Header "ERROR HANDLING" Every \s-1API\s0 call should return an \fBAck\fR response, whether \fISuccess\fR, \&\fIFailure\fR, or otherwise (depending on the \s-1API\s0 call). If it returns any non-success value, you can find an \fIErrors\fR entry in your return hash, whose value is an arrayref of hashrefs: .PP .Vb 2 \& [ { ErrorCode => 10002, \& LongMessage => "Invalid security header" }, \& \& { ErrorCode => 10030, \& LongMessage => "Some other error" }, ] .Ve .PP You can retrieve these errors like this: .PP .Vb 6 \& %response = $pp\->doSomeAPICall(); \& if( $response{Ack} ne \*(AqSuccess\*(Aq ) { \& for my $err ( @{$response{Errors}} ) { \& warn "Error: " . $err\->{LongMessage} . "\en"; \& } \& } .Ve .SH "TESTING" .IX Header "TESTING" Testing the \fBBusiness::PayPal::API::*\fR modules requires that you create a file containing your PayPal Developer Sandbox authentication credentials (e.g., \s-1API\s0 certificate authentication or 3\-Token authentication signature, etc.) and setting the \fB\s-1WPP_TEST\s0\fR environment variable to point to this file. .PP The format for this file is as follows: .PP .Vb 2 \& Username = your_api.username.com \& Password = your_api_password .Ve .PP and then \s-1ONE\s0 of the following options: .PP .Vb 1 \& a) supply 3\-token authentication signature \& \& Signature = xxxxxxxxxxxxxxxxxxxxxxxx \& \& b) supply PEM certificate credentials \& \& CertFile = /path/to/cert_key_pem.txt \& KeyFile = /path/to/cert_key_pem.txt \& \& c) supply PKCS#12 certificate credentials \& \& PKCS12File = /path/to/cert.p12 \& PKCS12Password = pkcs12_password .Ve .PP You may also set the appropriate HTTPS_* environment variables for b) and c) above (e.g., \s-1HTTPS_CERT_FILE, HTTPS_KEY_FILE,\s0 HTTPS_PKCS12_File, \s-1HTTPS_PKCS12_PASSWORD\s0) in lieu of putting this information in a file. .PP Then use \*(L"WPP_TEST=my_auth.txt make test\*(R" (for Bourne shell derivates) or \&\*(L"setenv \s-1WPP_TEST\s0 my_auth.txt && make test\*(R" (for C\-shell derivates). .PP See 'auth.sample.*' files in this package for an example of the file format. Variables are case\-*sensitive*. .PP Any of the following variables are recognized: .PP .Vb 3 \& Username Password Signature Subject \& CertFile KeyFile PKCS12File PKCS12Password \& BuyerEmail .Ve .PP Note: PayPal authentication may \fIfail\fR if you set the certificate environment variables and attempt to connect using 3\-token authentication (i.e., PayPal will use the first authentication credentials presented to it, and if they fail, the connection is aborted). .SH "TROUBLESHOOTING" .IX Header "TROUBLESHOOTING" .SS "PayPal Authentication Errors" .IX Subsection "PayPal Authentication Errors" If you are experiencing PayPal authentication errors (e.g., \*(L"Security header is not valid\*(R", \*(L"\s-1SSL\s0 negotiation failed\*(R", etc.), you should make sure: .PP .Vb 3 \& * your username and password match those found in your PayPal \& Business account sandbox (this is not the same as your regular \& account). \& \& * you\*(Aqre not trying to use your live username and password for \& sandbox testing and vice versa. \& \& * you are using a US Business Sandbox account, you may also need to have \& "PayPal Payments Pro" enabled. \& \& * if the sandbox works but "live" does not, make sure you\*(Aqve turned \& off the \*(Aqsandbox\*(Aq parameter correctly. Otherwise you\*(Aqll be \& passing your PayPal sandbox credentials to PayPal\*(Aqs live site \& (which won\*(Aqt work). \& \& * if you use certificate authentication, your certificate must be \& the correct one (live or sandbox) depending on what you\*(Aqre doing. \& \& * if you use 3\-Token authentication (i.e., Signature), you don\*(Aqt \& have any B parameters or B or B \& parameters in your constructor AND that none of the corresponding \& B environment variables are set. PayPal prefers \& certificate authentication since it occurs at connection time; if \& it fails, it will not try Signature authentication. \& \& Try clearing your environment: \& \& ## delete all HTTPS, SSL env \& delete $ENV{$_} for grep { /^(HTTPS|SSL)/ } keys %ENV; \& \& ## now put our own HTTPS env back in \& $ENV{HTTPS_CERT_FILE} = \*(Aq/var/path/to/cert.pem\*(Aq; \& \& ## create our paypal object \& my $pp = Business::PayPal::API\->new(...) \& \& * if you have already loaded Net::SSLeay (or IO::Socket::SSL), then \& Net::HTTPS will prefer to use IO::Socket::SSL. I don\*(Aqt know how \& to get SOAP::Lite to work with IO::Socket::SSL (e.g., \& Crypt::SSLeay uses HTTPS_* environment variables), so until then, \& you can use this hack: \& \& local $IO::Socket::SSL::VERSION = undef; \& \& $pp\->DoExpressCheckoutPayment(...); \& \& This will tell Net::HTTPS to ignore the fact that IO::Socket::SSL \& is already loaded for this scope and import Net::SSL (part of the \& Crypt::SSLeay package) for its \*(Aqconfigure()\*(Aq method. \& \& * if you receive a message like "500 Can\*(Aqt connect to \& api.sandbox.paypal.com:443 (Illegal seek)", you\*(Aqll need to make \& sure you have Crypt::SSLeay installed. It seems that other crypto \& modules don\*(Aqt do the certificate authentication quite as well, \& and LWP needs this to negotiate the SSL connection with PayPal. .Ve .PP See the \s-1DEBUGGING\s0 section below for further hints. .SS "PayPal Munging URLs" .IX Subsection "PayPal Munging URLs" PayPal seems to be munging my URLs when it returns. .PP SOAP::Lite follows the \s-1XML\s0 specification carefully, and encodes '&' and '<' characters before applying them to the \s-1SOAP\s0 document. PayPal does not properly URL-decode \s-1HTML\s0 entities '&' and '<' on the way back, so if you have an ampersand in your ReturnURL (for example), your customers will be redirected here: .PP .Vb 1 \& http://domain.tld/prog?arg1=foo&arg2=bar .Ve .PP instead of here: .PP .Vb 1 \& http://domain.tld/prog?arg1=foo&arg2=bar .Ve .PP Solution: .PP Use \s-1CDATA\s0 tags to wrap your request: .PP .Vb 1 \& ReturnURL => \*(Aq\*(Aq .Ve .PP You may also use semicolons instead of ampersands to separate your \s-1URL\s0 arguments: .PP .Vb 1 \& ReturnURL => \*(Aqhttp://domain.tld/prog?arg1=foo;arg2=bar\*(Aq .Ve .PP (thanks to Ollie Ready) .SH "DEBUGGING" .IX Header "DEBUGGING" You can see the raw \s-1SOAP XML\s0 sent and received by \&\fBBusiness::PayPal::API\fR by setting its \fB\f(CB$Debug\fB\fR variable: .PP .Vb 2 \& $Business::PayPal::API::Debug = 1; \& $pp\->SetExpressCheckout( %args ); .Ve .PP this will print the \s-1XML\s0 being sent, and dump a Perl data structure of the \s-1SOM\s0 received on \s-1STDERR\s0 (so check your error_log if running inside a web server). .PP If anyone knows how to turn a \s-1SOAP::SOM\s0 object into \s-1XML\s0 without setting \fB\fBoutputxml()\fB\fR, let me know. .SH "DEVELOPMENT" .IX Header "DEVELOPMENT" If you are a developer wanting to extend \fBBusiness::PayPal::API\fR for other PayPal \s-1API\s0 calls, you can review any of the included modules (e.g., \fIRefundTransaction.pm\fR or \fIExpressCheckout.pm\fR) for examples on how to do this until I have more time to write a more complete document. .PP But in a nutshell: .PP .Vb 1 \& package Business::PayPal::API::SomeAPI; \& \& use 5.008001; \& use strict; \& use warnings; \& \& use SOAP::Lite 0.67; \& use Business::PayPal::API (); \& \& our @ISA = qw(Business::PayPal::API); \& our @EXPORT_OK = qw( SomeAPIMethod ); \& \& sub SomeAPIMethod { \& ... \& } .Ve .PP Notice the \fB\f(CB@EXPORT_OK\fB\fR variable. This is \fInot\fR used by \fBExporter\fR (we don't load Exporter at all): it is a special variable used by \&\fBBusiness::PayPal::API\fR to know which methods to import when \&\fBBusiness::PayPal::API\fR is run like this: .PP .Vb 1 \& use Business::PayPal::API qw( SomeAPI ); .Ve .PP That is, \fBBusiness::PayPal::API\fR will import any subroutine into its own namespace from the \fB\f(CB@EXPORT_OK\fB\fR array. Now it can be used like this: .PP .Vb 3 \& use Business::PayPal::API qw( SomeAPI ); \& my $pp = Business::PayPal::API\->new( ... ); \& $pp\->SomeAPIMethod( ... ); .Ve .PP Of course, we also do a 'use Business::PayPal::API' in the module so that it can be used as a standalone module, if necessary: .PP .Vb 3 \& use Business::PayPal::API::SomeAPI; \& my $pp = Business::PayPal::API::SomeAPI\->new( ... ); ## same args as superclass \& $pp\->SomeAPIMethod( ... ); .Ve .PP Adding the \fB\f(CB@EXPORT_OK\fB\fR array in your module allows your module to be used in the most convenient way for the given circumstances. .SH "EXAMPLES" .IX Header "EXAMPLES" Andy Spiegl has kindly donated some example code (in German) for the ExpressCheckout \s-1API\s0 which may be found in the \fIeg\fR directory of this archive. Additional code examples for other APIs may be found in the \fIt\fR test directory. .SH "EXPORT" .IX Header "EXPORT" None by default. .SH "CAVEATS" .IX Header "CAVEATS" Because I haven't figured out how to make SOAP::Lite read the \s-1WSDL\s0 definitions directly and simply implement those (help, anyone?), I have essentially recreated all of those \s-1WSDL\s0 structures internally in this module. .PP (Note \- 6 Oct 2006: SOAP::Lite's \s-1WSDL\s0 support is moving ahead, but slowly. The methods used by this \s-1API\s0 are considered \*(L"best practice\*(R" and are safe to use). .PP As with all web services, if PayPal stop supporting their \s-1API\s0 endpoint, this module *may stop working*. You can help me keep this module up-to-date if you notice such an event occurring. .PP Also, I didn't implement a big fat class hierarchy to make this module \&\*(L"academically\*(R" correct. You'll notice that I fudged colliding parameter names in \fBDoExpressCheckoutPayment\fR and similar fudging may be found in \fBGetTransactionDetails\fR. The good news is that this was written quickly, works, and is dead-simple to use. The bad news is that this sort of collision might occur again as more and more data is sent in the \s-1API\s0 (call it 'eBay \s-1API\s0 bloat'). I'm willing to take the risk this will be rare (PayPal\*(--please make it rare!). .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Wherein I acknowledge all the good folks who have contributed to this module in some way: .IP "\(bu" 4 Daniel P. Hembree .Sp for authoring the AuthorizationRequest, CaptureRequest, DirectPayments, ReauthorizationRequest, and VoidRequest extensions. .IP "\(bu" 4 .Sp for finding some \s-1API\s0 typos in the ExpressCheckout \s-1API\s0 .IP "\(bu" 4 Andy Spiegl .Sp for giving me the heads-up on PayPal's new 3\-token auth \s-1URI\s0 and for a sample command-line program (found in the 'eg' directory) demonstrating the ExpressCheckout \s-1API.\s0 .IP "\(bu" 4 Ollie Ready .Sp for the heads-up on the newest 3\-token auth \s-1URI\s0 as well as a pile of documentation inconsistencies. .IP "\(bu" 4 Michael Hendricks .Sp for a patch that adds ShippingTotal to the DirectPayments module. .IP "\(bu" 4 Erik Aronesty, Drew Simpson via rt.cpan.org (#28596) .Sp for a patch to fix \fBgetFields()\fR when multiple items are returned .IP "\(bu" 4 Sebastian Böhm via email, \s-1SDC\s0 via rt.cpan.org (#38915) .Sp for a heads-up that the PayPal documentation for MassPay \s-1API\s0 was wrong regarding the \fIUniqueId\fR parameter. .IP "\(bu" 4 Jonathon Wright via email .Sp for patches for \fBExpressCheckout\fR and \fBRecurringPayments\fR that implement \fIBillingAgreement\fR and \fIDoReferenceTransaction\fR \s-1API\s0 calls. .SH "SEE ALSO" .IX Header "SEE ALSO" SOAP::Lite, PayPal User Guide , PayPal \s-1API\s0 Reference .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Scott Wiersdorf .IP "\(bu" 4 Danny Hembree .IP "\(bu" 4 Bradley M. Kuhn .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2006\-2017 by Scott Wiersdorf, Danny Hembree, Bradley M. Kuhn. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.