NAME

Business::PayPal::API - PayPal API

SYNOPSIS

  use Business::PayPal::API;

  ## certificate authentication
  my $pp = new Business::PayPal::API
            ( Username       => 'my_api1.domain.tld',
              Password       => 'this_is_my_password',
              PKCS12File     => '/path/to/cert.pck12',
              PKCS12Password => '/path/to/certpw.pck12',
              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 authentication
  my $pp = new Business::PayPal::API
            ( Username   => 'my_api1.domain.tld',
              Password   => 'Xdkis9k3jDFk39fj29sD9',  ## supplied by PayPal
              Signature  => 'f7d03YCpEjIF3s9Dk23F2V1C1vbYYR3ALqc7jm0UrCcYm-3ksdiDwjfSeii',  ## ditto
              sandbox    => 1 );

DESCRIPTION

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

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

new

Creates a new Business::PayPal::API object. This is usually invoked from a subclass.

A note about certificate authentication: You may use 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 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

Password

Required. If you use certificate authentication, this is the PayPal API password you created yourself when you setup your certificate. If you use 3-token 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 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).

If you are experiencing PayPal authentication errors, 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 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.

   * If your 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 make IO::Socket::SSL use the right certificate from
     SOAP::Lite (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.

See the DEBUGGING section below for further hints.

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 );

these will print the XML being sent, and a Perl data structure of the SOM received 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 RefundTransaction.pm or ExpressCheckout.pm for examples on how to do this until I have more time to write a document.

In a nutshell:

  package Business::PayPal::API::SomeAPIFunction;

  use 5.008001;
  use strict;
  use warnings;

  use SOAP::Lite 0.67;
  use Business::PayPal::API ();

  our @ISA = qw(Business::PayPal::API);

  sub SomeAPIFunction {
   ...
  }

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.

If PayPal changes their API (adds, removes, or changes parameters), this module *may stop working*. I do not know if PayPal will preserve backward compatibility. That said, you can help me keep this module up-to-date if you notice such an event occuring.

While this module was written, PayPal added 3-token authentication, which while being trivial to support and get working, is a good example of how quickly non-WSDL SOAP can get behind.

Also, I didn't implement a big fat class hierarchy to make this module "academically" correct. You'll notice that I fudged two colliding parameter names in DoExpressCheckoutPayment as a result. 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!).

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

cpanm Business::PayPal::API

perl -MCPAN -e shell
install Business::PayPal::API