view release on metacpan or  search on metacpan

lib/Business/PayPal/API.pm  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 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(...)

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

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

=head1 DEBUGGING

You can see the raw SOAP XML sent and received by
B<Business::PayPal::API> by setting its B<$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 B<outputxml()>, let me know.

=head1 DEVELOPMENT

If you are a developer wanting to extend B<Business::PayPal::API> for
other PayPal API calls, you can review any of the included modules
(e.g., F<RefundTransaction.pm> or F<ExpressCheckout.pm>) for examples