Provided by: libbusiness-paypal-api-perl_0.70-1_all bug

NAME

       Business::PayPal::API - PayPal API

SYNOPSIS

         use Business::PayPal::API qw( ExpressCheckout GetTransactionDetails );

         ## certificate authentication
         my $pp = new Business::PayPal::API
                   ( Username       => 'my_api1.domain.tld',
                     Password       => 'this_is_my_password',
                     PKCS12File     => '/path/to/cert.pkcs12',
                     PKCS12Password => '(pkcs12 password)',
                     sandbox        => 1 );

         ## PEM cert authentication
         my $pp = new Business::PayPal::API
                   ( Username    => 'my_api1.domain.tld',
                     Password    => 'this_is_my_password',
                     CertFile    => '/path/to/cert.pem',
                     KeyFile     => '/path/to/cert.pem',
                     sandbox     => 1 );

         ## 3-token (Signature) authentication
         my $pp = new Business::PayPal::API
                   ( Username   => 'my_api1.domain.tld',
                     Password   => 'Xdkis9k3jDFk39fj29sD9',  ## supplied by PayPal
                     Signature  => 'f7d03YCpEjIF3s9Dk23F2V1C1vbYYR3ALqc7jm0UrCcYm-3ksdiDwjfSeii',  ## ditto
                     sandbox    => 1 );

         my %response = $pp->SetExpressCheckout( ... );

DESCRIPTION

       Business::PayPal::API supports both certificate authentication and the new 3-token
       "Signature" authentication.

       It also support PayPal's development sandbox for testing. See the sandbox parameter to
       new() below for details.

       Business::PayPal::API can import other API derived classes:

         use Business::PayPal::API qw( RefundTransaction );

       This allows for much more concise and intuitive usage. For example, these two statements
       are equivalent:

         use Business::PayPal::API::RefundTransaction;
         my $pp = new Business::PayPal::API::RefundTransaction( ... );
         $pp->RefundTransaction( ... );

       and more concisely:

         use Business::PayPal::API qw( RefundTransaction );
         my $pp = new Business::PayPal::API( ... );
         $pp->RefundTransaction( ... );

       The advantage of this becomes clear when you need to use multiple API 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 API object used to invoke
       various PayPal APIs with the same object:

         use Business::PayPal::API qw( GetTransactionDetails
                                       TransactionSearch
                                       RefundTransaction );
         my $pp = new Business::PayPal::API( ... );
         my $records = $pp->TransactionSearch( ... );

         my %details = $pp->GetTransactionDetails( ... );

         my %resp = $pp->RefundTransaction( ... );

       However, you may certainly use just the subclass if that's all you need. Every subclass
       should work as its own self-contained API.

       For details on Business::PayPal::API::* subclasses, see each subclass's individual
       documentation.

   new
       Creates a new Business::PayPal::API object.

       A note about certificate authentication: PayPal (and this module) support either PKCS#12
       certificate authentication or PEM certificate authentication. See options below.

       Username
           Required. This is the PayPal API username, usually in the form of
           'my_api1.mydomain.tld'. You can find or create your API 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:

             My Account -> Profile -> API Access -> Request API Credentials

           Please see the PayPal API Reference and PayPal Sandbox User Guide for details on
           creating a PayPal business account and sandbox account for testing.

       Password
           Required. If you use certificate authentication, this is the PayPal API password
           created when you setup your certificate. If you use 3-token (Signature)
           authentication, this is the password PayPal assigned you, along with the "API User
           Name" and "Signature Hash".

       Subject
           Optional. This is used by PayPal to authenticate 3rd party billers using your account.
           See the documents in "SEE ALSO".

       Signature
           Required for 3-token (Signature) authentication. This is the "Signature Hash" you
           received when you did "Request API Credentials" in your PayPal Business Account.

       PKCS12File
           Required for PKCS#12 certificate authentication, unless the HTTPS_PKCS12_FILE
           environment variable is already set.

           This contains the path to your private key for PayPal authentication. It is used to
           set the HTTPS_PKCS12_FILE environment variable. You may set this environment variable
           yourself and leave this field blank.

       PKCS12Password
           Required for PKCS#12 certificate authentication, unless the HTTPS_PKCS12_PASSWORD
           environment variable is already set.

           This contains the PKCS#12 password for the key specified in PKCS12File. It is used to
           set the HTTPS_PKCS12_PASSWORD environment variable. You may set this environment
           variable yourself and leave this field blank.

       CertFile
           Required for PEM certificate authentication, unless the HTTPS_CERT_FILE environment
           variable is already set.

           This contains the path to your PEM 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 HTTPS_CERT_FILE environment variable. You may set
           this environment variable yourself and leave this field blank.

           You may combine both certificate and private key into one file and set CertFile and
           KeyFile to the same path.

       KeyFile
           Required for PEM certificate authentication, unless the HTTPS_KEY_FILE environment
           variable is already set.

           This contains the path to your PEM 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 HTTPS_KEY_FILE environment variable. You may set
           this environment variable yourself and leave this field blank.

           You may combine both certificate and private key into one file and set CertFile and
           KeyFile to the same path.

       sandbox
           Required. If set to true (default), Business::PayPal::API 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*.

           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 Verified status in the sandbox).

           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 "SEE ALSO"
           for references.

           PayPal's sandbox reference:

           <https://www.paypal.com/IntegrationCenter/ic_sandbox.html>

ERROR HANDLING

       Every API call should return an Ack response, whether Success, Failure, or otherwise
       (depending on the API call). If it returns any non-success value, you can find an Errors
       entry in your return hash, whose value is a listref of hashrefs:

        [ { ErrorCode => 10002,
            LongMessage => "Invalid security header" },

          { ErrorCode => 10030,
            LongMessage => "Some other error" }, ]

       You can retrieve these errors like this:

         %response = $pp->doSomeAPICall();
         if( $response{Ack} ne 'Success' ) {
             for my $err ( @{$response{Errors}} ) {
                 warn "Error: " . $err->{LongMessage} . "\n";
             }
         }

TESTING

       Testing the Business::PayPal::API::* modules requires that you create a file containing
       your PayPal Developer Sandbox authentication credentials (e.g., API certificate
       authentication or 3-Token authentication signature, etc.) and setting the WPP_TEST
       environment variable to point to this file.

       The format for this file is as follows:

         Username = your_api.username.com
         Password = your_api_password

       and then ONE of the following options:

         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

       You may also set the appropriate HTTPS_* environment variables for b) and c) above (e.g.,
       HTTPS_CERT_FILE, HTTPS_KEY_FILE, HTTPS_PKCS12_File, HTTPS_PKCS12_PASSWORD) in lieu of
       putting this information in a file.

       Then use "WPP_TEST=my_auth.txt make test" (for Bourne shell derivates) or "setenv WPP_TEST
       my_auth.txt && make test" (for C-shell derivates).

       See 'auth.sample.*' files in this package for an example of the file format. Variables are
       case-*sensitive*.

       Any of the following variables are recognized:

         Username Password Signature Subject
         CertFile KeyFile PKCS12File PKCS12Password
         BuyerEmail

       Note: PayPal authentication may fail 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).

TROUBLESHOOTING

   PayPal Authentication Errors
       If you are experiencing PayPal authentication errors (e.g., "Security header is not
       valid", "SSL negotiation failed", etc.), you should make sure:

          * your username and password match those found in your PayPal
            Business account sandbox (this is not the same as your regular
            account.

          * you're not trying to use your live username and password for
            sandbox testing and vice versa.

          * if the sandbox works but "live" does not, make sure you've turned
            off the 'sandbox' parameter correctly. Otherwise you'll be
            passing your PayPal sandbox credentials to PayPal's live site
            (which won't work).

          * if you use certificate authentication, your certificate must be
            the correct one (live or sandbox) depending on what you're doing.

          * if you use 3-Token authentication (i.e., Signature), you don't
            have any B<PKCS12*> parameters or B<CertFile> or B<KeyFile>
            parameters in your constructor AND that none of the corresponding
            B<HTTPS_*> 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} = '/var/path/to/cert.pem';

                ## create our paypal object
                my $pp = new Business::PayPal::API...

          * if you have already loaded Net::SSLeay (or IO::Socket::SSL), then
            Net::HTTPS will prefer to use IO::Socket::SSL. I don't 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 'configure()' method.

          * if you receive a message like "500 Can't connect to
            api.sandbox.paypal.com:443 (Illegal seek)", you'll need to make
            sure you have Crypt::SSLeay installed. It seems that other crypto
            modules don't do the certificate authentication quite as well,
            and LWP needs this to negotiate the SSL connection with PayPal.

       See the DEBUGGING section below for further hints.

   PayPal Munging URLs
       PayPal seems to be munging my URLs when it returns.

       SOAP::Lite follows the XML specification carefully, and encodes '&' and '<' characters
       before applying them to the SOAP document. PayPal does not properly URL-decode HTML
       entities '&amp;' and '&lt;' on the way back, so if you have an ampersand in your ReturnURL
       (for example), your customers will be redirected here:

         http://domain.tld/prog?arg1=foo&amp;arg2=bar

       instead of here:

         http://domain.tld/prog?arg1=foo&arg2=bar

       Solution:

       Use CDATA tags to wrap your request:

         ReturnURL => '<![CDATA[http://domain.tld/prog?arg1=foo&arg2=bar]]>'

       You may also use semicolons instead of ampersands to separate your URL arguments:

         ReturnURL => 'http://domain.tld/prog?arg1=foo;arg2=bar'

       (thanks to Ollie Ready)

DEBUGGING

       You can see the raw SOAP XML sent and received by Business::PayPal::API by setting it's
       $Debug variable:

         $Business::PayPal::API::Debug = 1;
         $pp->SetExpressCheckout( %args );

       this will print the XML being sent, and dump a Perl data structure of the SOM received on
       STDERR (so check your error_log if running inside a web server).

       If anyone knows how to turn a SOAP::SOM object into XML without setting outputxml(), let
       me know.

DEVELOPMENT

       If you are a developer wanting to extend Business::PayPal::API for other PayPal API calls,
       you can review any of the included modules (e.g., RefundTransaction.pm or
       ExpressCheckout.pm) for examples on how to do this until I have more time to write a more
       complete document.

       But in a nutshell:

         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 {
          ...
         }

       Notice the @EXPORT_OK variable. This is not used by Exporter (we don't load Exporter at
       all): it is a special variable used by Business::PayPal::API to know which methods to
       import when Business::PayPal::API is run like this:

         use Business::PayPal::API qw( SomeAPI );

       That is, Business::PayPal::API will import any subroutine into its own namespace from the
       @EXPORT_OK array. Now it can be used like this:

         use Business::PayPal::API qw( SomeAPI );
         my $pp = new Business::PayPal::API( ... );
         $pp->SomeAPIMethod( ... );

       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:

         use Business::PayPal::API::SomeAPI;
         my $pp = new Business::PayPal::API::SomeAPI( ... ); ## same args as superclass
         $pp->SomeAPIMethod( ... );

       Adding the @EXPORT_OK array in your module allows your module to be used in the most
       convenient way for the given circumstances.

EXAMPLES

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

EXPORT

       None by default.

CAVEATS

       Because I haven't figured out how to make SOAP::Lite read the WSDL definitions directly
       and simply implement those (help, anyone?), I have essentially recreated all of those WSDL
       structures internally in this module.

       (Note - 6 Oct 2006: SOAP::Lite's WSDL support is moving ahead, but slowly. The methods
       used by this API are considered "best practice" and are safe to use).

       As with all web services, if PayPal stop supporting their API endpoint, this module *may
       stop working*. You can help me keep this module up-to-date if you notice such an event
       occuring.

       Also, I didn't implement a big fat class hierarchy to make this module "academically"
       correct. You'll notice that I fudged colliding parameter names in DoExpressCheckoutPayment
       and similar fudging may be found in GetTransactionDetails. 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 API (call it 'eBay API
       bloat'). I'm willing to take the risk this will be rare (PayPal--please make it rare!).

ACKNOWLEDGEMENTS

       Wherein I acknowledge all the good folks who have contributed to this module in some way:

       •   Daniel P. Hembree

           for authoring the AuthorizationRequest, CaptureRequest, DirectPayments,
           ReauthorizationRequest, and VoidRequest extensions.

           Danny's contact information may be found in the AUTHOR section of the above modules.

       •   <jshiles at base16consulting daught com>

           for finding some API typos in the ExpressCheckout API

       •   Andy Spiegl <paypalcheckout.Spiegl@kascada.com>

           for giving me the heads-up on PayPal's new 3-token auth URI and for a sample command-
           line program (found in the 'eg' directory) demonstrating the ExpressCheckout API.

       •   Ollie Ready <oready at drjays daught com>

           for the heads-up on the newest 3-token auth URI as well as a pile of documentation
           inconsistencies.

       •   Michael Hendricks <michael at ndrix daught org>

           for a patch that adds ShippingTotal to the DirectPayments module.

       •   Erik Aronesty, Drew Simpson via rt.cpan.org (#28596)

           for a patch to fix getFields() when multiple items are returned

       •   Sebastian BA~Xhm via email, SDC via rt.cpan.org (#38915)

           for a heads-up that the PayPal documentation for MassPay API was wrong regarding the
           UniqueId parameter.

       •   Jonathon Wright via email

           for patches for ExpressCheckout and RecurringPayments that implement BillingAgreement
           and DoReferenceTransaction API calls.

SEE ALSO

       SOAP::Lite, <https://www.paypal.com/IntegrationCenter/ic_pro_home.html>,
       <https://www.paypal.com/IntegrationCenter/ic_expresscheckout.html>,
       <https://www.sandbox.paypal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf>,
       <https://developer.paypal.com/en_US/pdf/PP_APIReference.pdf>

AUTHOR

       Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2006, 2007 by Scott Wiersdorf

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of
       Perl 5 you may have available.