NAME

Business::PayPal::WPP::ExpressCheckout - Simplified Express Checkout API

SYNOPSIS

use Business::PayPal::WPP::ExpressCheckout;

## certificate authentication
my $pp = new Business::PayPal::WPP::ExpressCheckout
          ( Username   => 'my_api1.domain.tld',
            Password   => 'this_is_my_password',
            CertFile   => '/path/to/cert.pck12',
            CertPass   => '/path/to/certpw.pck12',
            sandbox    => 1 );

## PEM cert authentication
my $pp = new Business::PayPal::WPP::ExpressCheckout
          ( Username   => 'my_api1.domain.tld',
            Password   => 'this_is_my_password',
            CertBoth   => '/path/to/cert.pem',
            sandbox    => 1 );

## 3-token authentication
my $pp = new Business::PayPal::WPP::ExpressCheckout
          ( Username   => 'my_api1.domain.tld',
            Password   => 'Xdkis9k3jDFk39fj29sD9',  ## supplied by PayPal
            Signature  => 'f7d03YCpEjIF3s9Dk23F2V1C1vbYYR3ALqc7jm0UrCcYm-3ksdiDwjfSeii',  ## ditto
            sandbox    => 1 );

my $token = $pp->SetExpressCheckout
              ( OrderTotal => '55.43',   ## defaults to USD
                ReturnURL  => 'http://site.tld/return.html',
                CancelURL  => 'http://site.tld/canceltation.html', );

... time passes, buyer validates the token with PayPal ...

my %details = $pp->GetExpressCheckoutDetails($token);

## now ask PayPal to xfer the money
my %payinfo = $pp->DoExpressCheckoutPayment( Token => $token,
                                             PaymentAction => 'Sale',
                                             PayerID => $details{PayerID},
                                             OrderTotal => '55.43' );

DESCRIPTION

Business::PayPal::WPP::ExpressCheckout (hereafter BPWE) aims to make PayPal's "Website Payments Pro" (WPP) Express Checkout API as simple as possible. With a little help from SOAP::Lite, we can whittle an ExpressCheckout transaction down to a few simple API calls.

BPWE support both certificate authentication and the new 3-token authentication.

new

Creates a new BPWE object.

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.

CertFile

Required for certificate authentication if you're not using CertBoth and if you haven't already set the HTTPS_PCK12_FILE environment variable. This contains the path to your private key for PayPal authentication. It is used to set the HTTPS_PCK12_FILE environment variable. You may set this environment variable yourself and leave this field blank.

CertPass

Required for certificate authentication if you're not using CertBoth and if you haven't already set the HTTPS_PCK12_PASSWORD environment variable. This contains the path to your private key for PayPal authentication. It is used to set the HTTPS_PCK12_PASSWORD environment variable. You may set this environment variable yourself and leave this field blank.

CertBoth

Required for certificate authentication if you're not using CertFile and CertPass and if you haven't already set the HTTPS_KEY_FILE and HTTPS_CERT_FILE envirionment variables. 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_KEY_FILE and HTTPS_CERT_FILE environment variables. You may set these environment variables yourself and leave this field blank.

sandbox

Required. If set to true (default), BPWE 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*.

SetExpressCheckout

Implements PayPal's WPP SetExpressCheckout API call. Supported parameters include:

Token
OrderTotal
currencyID
MaxAmount
OrderDescription
Custom
InvoiceID
ReturnURL
CancelURL
Address
ReqConfirmShipping
NoShipping
AddressOverride
LocaleCode
PageStyle
'cpp-header-image'
'cpp-header-border-color'
'cpp-header-back-color'
'cpp-payflow-color'
PaymentAction
BuyerEmail

as described in the PayPal "Web Services API Reference" document. The default currency setting is 'USD' if not otherwise specified.

Returns a scalar variable that represents the PayPal transaction token ("Token").

Required fields:

OrderTotal, ReturnURL, CancelURL.

GetExpressCheckoutDetails

Implements PayPal's WPP SetExpressCheckout API call. Supported parameters include:

Token

as described in the PayPal "Web Services API Reference" document. This is the same token you received from SetExpressCheckout.

Returns a hash with the following keys:

Token
Custom
InvoiceID
ContactPhone
Payer
PayerID
PayerStatus
FirstName
LastName
PayerBusiness
Name
Street1
Street2
CityName
StateOrProvince
PostalCode
Country

Required fields:

Token

DoExpressCheckoutPayment

Implements PayPal's WPP SetExpressCheckout API call. Supported parameters include:

Token  
PaymentAction (defaults to 'Sale' if not supplied)
PayerID
currencyID

OrderTotal
OrderDescription
ItemTotal
ShippingTotal  
HandlingTotal  
TaxTotal  
Custom  
InvoiceID  
ButtonSource  
NotifyURL  

ST_Name  
ST_Street1  
ST_Street2  
ST_CityName  
ST_StateOrProvice  
ST_Country  
ST_PostalCode  

PDI_Name  
PDI_Amount  
PDI_Number  
PDI_Quantity  
PDI_Tax

as described in the PayPal "Web Services API Reference" document.

Returns a hash with the following keys:

Token  
TransactionID  
TransactionType  
PaymentType  
PaymentDate  
GrossAmount  
FeeAmount  
SettleAmount  
TaxAmount  
ExchangeRate  
PaymentStatus  
PendingReason

Required fields:

Token, PayerID, OrderTotal

DEBUGGING

You can see the raw SOAP XML sent and received by BPWE by setting it's $Debug variable:

$Business::PayPal::WPP::ExpressCheckout::Debug = 1;
$pp->SetExpressCheckout( %args );

these will print on STDERR (so check your error_log if running inside a web server).

Unfortunately, while doing this, it also doesn't put things back the way they should be, so this should not be used in a production environment to troubleshoot (until I get this fixed). Patches gladly accepted which would let me get the correct SOM object back after serialization.

Summary: until this bug is fixed, don't use $Debug except in a sandbox.

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

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE

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.

To install Business::PayPal::WPP::ExpressCheckout, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Business::PayPal::WPP::ExpressCheckout

CPAN shell

perl -MCPAN -e shell
install Business::PayPal::WPP::ExpressCheckout

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

new

SetExpressCheckout

GetExpressCheckoutDetails

DoExpressCheckoutPayment

DEBUGGING

EXPORT

CAVEATS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions