view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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

# DESCRIPTION

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

It also supports 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 = Business::PayPal::API::RefundTransaction->new( ... );
    $pp->RefundTransaction( ... );

and more concisely:

    use Business::PayPal::API qw( RefundTransaction );
    my $pp = Business::PayPal::API->new( ... );
    $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 = Business::PayPal::API->new( ... );
    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"](#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.

README.md  view on Meta::CPAN

- **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"](#see-also) for references.

    PayPal's sandbox reference:

    [https://www.paypal.com/IntegrationCenter/ic\_sandbox.html](https://www.paypal.com/IntegrationCenter/ic_sandbox.html)

- **proxy\_url**

    Optional. When set, the proxy at the specified URL will be used for outbound
    connections.

- **timeout**

    Optional. Set the timeout in seconds. Defaults to 30 seconds.

# NAME

Business::PayPal::API - PayPal API

# 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 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";
        }
    }

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

    * 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