view release on metacpan or  search on metacpan

lib/Business/PayPal/API.pm  view on Meta::CPAN

Business::PayPal::API - PayPal API

=head1 ERROR HANDLING

Every API call should return an B<Ack> response, whether I<Success>,
I<Failure>, or otherwise (depending on the API call). If it returns
any non-success value, you can find an I<Errors> entry in your return
hash, whose value is an arrayref 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";
      }
  }

=head1 TESTING

Testing the B<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 B<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 I<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).

=head1 TROUBLESHOOTING

=head2 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.

   * 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'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 = Business::PayPal::API->new(...)