view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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.

    * 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(...)

    * 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;amp;' and '&amp;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 its **$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