PaypalExpress

Interchange PayPal Express Payments Module.

Synopsis

&charge = paypalexpress

[charge route="paypalexpress" param1="value1" param2="value2"]

Prerequisites

SOAP::Lite
XML::Parser
MIME::Base64
URI
libwww-perl
Crypt::SSLeay
IO::Socket::SSL

Warning

You will need version 0.97 through 0.99x of the IO::Socket::SSL module in order to avoid the "illegal seek" error, unless you find a later version that works.

Description

The Vend::Payment::PaypalExpress module implements the paypalexpress() subroutine for use with Interchange. It is compatible on a call level with the other Interchange payment modules. In theory (and even usually in practise) you could switch from another payment module to PaypalExpress with a few configuration file changes.

The following actions are supported:

Take a "Sale", "Order" or "Authorization" (The default is "sale").
Make a "Refund".
Make a "Capture", "Auth" or "Reauth" on an "order" or "authorization" (TODO).
Make a "Masspay" payment to several recipients (max 250) simultaneously (TOFINISH).
Handle IPN messages from recurring payments or other operations (TODO).

Some of these actions require a suitable terminal interface. Such a terminal is available at kiwi.zolotek.net , along with the current version of this module. PayPal have their own virtual terminal, but state that it is "only available in the USA". This release of the module has had the "TODO" parts removed, but these will be put back when I get around to getting them finished.

To enable this module, place this directive in your "interchange.cfg" file:

Require module Vend::Payment::PaypalExpress

This must be in interchange.cfg or a file included from it.

Make sure CreditCardAuto is off, which is the default in the Standard ecommerce demo.

The "mode" can be named anything, but the "gateway" parameter must be set to "paypalexpress". To make it the default payment gateway for all credit card transactions in a specific website, you can set the following in catalog.cfg:

Variable MV_PAYMENT_MODE paypalexpress

It uses several of the standard settings from Interchange payment. Any time we speak of a setting, it is obtained either first from the tag/call options, then from an Interchange order Route named after the mode, then finally a default global payment Variable. For example, the id parameter would be specified by:

[charge route=paypalexpress id=YourPaypalExpressID]

Route paypalexpress id YourPaypalExpressID

Variable MV_PAYMENT_ID YourPaypalExpressID

To have PayPal co-operate with your normal payment service provider, i.e. Authorize.net, do the following:

Deactivate the MV_PAYMENT_MODE variable in catalog.cfg and your VariableDatabase (i.e. products/variable.txt).
Log onto your PayPal Business (not Personal) account and go to "Profile" -> "API access" -> "Request API Credential" -> "Signature". This will generate a user ID, a password and a signature for you to use.

Add the required parts of the following Route definition to your "catalog.cfg" file:

Route paypalexpress <<EOR
id    xxx (Required)
password    xxx (Required)
signature xxx (Required. Use the three-token system - not the certificate system at PayPal)
returnurl your_full_URI/paypalgetrequest.html (Required)
cancelurl your_full_URI/your_cancellation_page.html (Required)
host    api.sandbox.paypal.com (Test host)
host    api-3t.paypal.com (Live host. Use either this or the test host, but not both)
currency    EUR|GBP|USD|CAD|AUD (Optional. Defaults to USD)
pagestyle xxx (Optional. Set up at PayPal)
paymentaction Sale (Optional. Defaults to "Sale")
headerimg xxx (Optional. Must be served from a secure URI if used)
EOR

Add to the following to your OrderProfile file (usually "etc/profiles.order"):

__NAME__ paypalexpress
__COMMON_ORDER_PROFILE__
&fatal = yes
email=required
email=email
&set=mv_payment PaypalExpress
&set=psp Paypal
&set=mv_payment_route paypalexpress
&final = yes
&setcheck = payment_method paypalexpress
__END__

Within the "credit_card" section of your OrderProfile file, change both instances of "MV_PAYMENT_MODE" to "MV_PAYMENT_BANK" and add the following:

&set=psp __MV_PAYMENT_BANK__
&set=mv_payment_route authorizenet

(or your preferred gateway) as the last entries in the section, and then add the following to your catalog.cfg file:

Variable MV_PAYMENT_BANK "foo"

where "foo" is the name of your gateway or acquirer, formatted as you want it to appear on the receipt. For example, "Bank of America", rather than "boa", or "AuthorizeNet", rather than "authorizenet" etc.
In "etc/log_transction", change:

[elsif variable MV_PAYMENT_MODE]

to:

[elsif value mv_order_profile eq credit_card]

and within the same section change the following two instances of "[var MV_PAYMENT_MODE]" to "[value mv_payment_route]"

Just after the "credit_card section", add the following:

[elsif value mv_order_profile eq paypalexpress]
[calcn]
return if $Scratch->{tmp_total} == $Scratch->{tmp_remaining};
my $msg = sprintf "Your PayPal account was charged %.2f", $Scratch->{tmp_remaining};
$Scratch->{pay_cert_total} = $Scratch->{tmp_total} - $Scratch->{tmp_remaining};
$Scratch->{charge_total_message} = $msg;
return "PayPal will be charged $Scratch->{tmp_remaining}";
[/calcn]
Charging with payment mode=paypalexpress
[tmp name="charge_succeed"][charge route="paypalexpress" pprequest="dorequest" amount="[scratch tmp_remaining]" order_id="[value mv_transaction_id]"][/tmp]
[if scratch charge_succeed]
[set do_invoice]1[/set]
[set do_payment]1[/set]
Real-time charge succeeded. ID=[data session payment_id] amount=[scratch tmp_remaining]
[else]
Real-time charge FAILED. Reason: [data session payment_error]
[calcn]
foreach (qw{charge_total_message pay_cert_total}) {
delete $Scratch->{$_};
}
die errmsg(
"Real-time charge failed. Reason: %s\n",
errmsg($Session->{payment_error}),
);
undef;
[/calcn]
[/else]
[/if]
[/elsif]

The above runs the final PayPal "charge" route, handles deductions for gift certificates from the amount payable and handles errors in the same way as the previous "credit_card" section does.

Add "psp", "pptransactionid", "pprefundtransactionid" and "ppcorrelationid" columns to your "transactions" table.

Find the line, close to the end of the "etc/log_transaction" file that looks like this:

[import table=transactions type=LINE continue=NOTES no-commit=1]"

and add the following:

psp: [value psp]
pptransactionid: [calcn] $result{TransactionID}; [/calcn]
pprefundtransactionid: [calcn] $result->{RefundTransactionID}; [/calcn]
ppcorrelationid: [calcn] $result{CorrelationID}; [/calcn]

The above will provide a record of which transactions went through which payment service providers, as well as PayPal's returned IDs. The "CorrelationID" (ppcorrelationid) is the one you will need to quote during dispute resolution.

Create a page called "ord/paypalsetrequest.html", with the following content, and make it the target of any "PayPal" buttons or links.

[value name="pprequest" set="" hide=1]
[charge route="paypalexpress" pprequest="setrequest"]

[if scratch token]
[bounce href="https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=[scratch token]"]
[else]
[bounce href="[area href=ord/checkout secure=1]"]
[/else]
[/if]

Create a page called "ord/paypalgetrequest.html", with the following content, and make it the target of the "returnurl" from PayPal:

[charge route="paypalexpress" pprequest="getrequest"]
[bounce href="[area href=ord/paypalcheckout secure=1]"]
Create a page called "ord/paypalcheckout.html". This should display just the basket and address, or whatever you choose for the final pages, plus a submit button, with the following setup, to finalise the order:

mv_order_profile=paypalexpress
pprequest = dorequest
mv_todo=submit

You may then use PaypalExpress for any transaction, where the "mv_order_profile" is set to "paypalexpress", and still use the "credit_card" mv_order_profile for other transactions, such as for Authorize.net. Of course, if PaypalExpress is to be your only payment method, then simply add the following to you "catalog.cfg" file:

Variable MV_PAYMENT_MODE paypalexpress

just before the paypalexpress Route entries, and this route will be the default.

Note

Because PayPal do not recognise "UK" as a country (they only recognise "GB"), you need to set up shipping in your country table for "GB" as well as, or instead of, "UK".

Note

PayPal do not return the customer's telephone number, so you may need to adjust your order profiles to compensate.

Payment process flow

The first button for PayPal goes to the "ord/paypalsetrequest.html" page, which sends a request to PayPal to initialise the transaction and gets a token back in return.

If PayPal fails to send back a token, then the module refreshes that page with an error message suggesting that the customer should use your normal payment service provider, and shows the cards that you accept.

Once the token is read, your customer is taken to PayPal to login and choose a payment method. Once that is done, the customer will return to your website's "ord/paypalgetrequest.html" page.

The "ord/paypalgetrequest.html" page collects the customer's full address, as held by PayPal and then bounces to the final "ord/paypalcheckout.html" page, which populates the form with the address details.

If you have both shipping and billing forms on the "ord/paypalcheckout.html" page, the shipping address will be populated by default. You may force the billing form to be populated instead by sending the following one the initial "setrequest" form:

<input type="hidden" name="pp_use_billing_address" value="1">

Lastly, the customer clicks on the final "Pay Now" button and the transaction is complete.

Settings

Name

Description

Your PaypalExpress business (not personal) account ID.

password

Your PaypalExpress account password.

signature

Use the 3-token system - not the certificate system at PayPal.

host

The PayPal hostname to use. I.e. api.sandbox.paypal.com for testing or api-3t.paypal.com for live transactions.

currency

The currency of the transaction amount. Must be one of "EUR", "GBP", "USD", "CAD" or "AUD". The default is "USD".

returnurl

The full return URI of a page on your website that will handle the payment status returned by PayPal, and will display an appropriate status page to the user. This must be a full URI, for example:

http://www.example.com/cgi-bin/example/ord/paypalgetrequest.html

You may optionally set the return URI in the page as follows:

<input type="hidden" name="returnurl" value="your_page_uri">,

cancelurl

The full return URI of a page on your website that will handle the case where a user cancels the transaction, and will display an appropriate status page to the user. This must be a full URI, for example:

http://www.example.com/cgi-bin/example/ord/paypalcancelrequest.html

You may optionally set the return URI in the page as follows:

<input type="hidden" name="returnurl" value="your_page_uri">,

pagestyle

Optional. Set up at PayPal.

headerimg

Optional image to be displayed on the PayPal payment pages. This must be a HTTPS (SSL) page if it is used.

paymentaction

The type of transaction to be run. Valid values are as follows:

Sale (This is the default action)
Order
Authorization
Refund

The following settings may be specified either in a route or in a page:

Option	Description
reqconfirmshipping	This specifies that a PayPal customer must have a confirmed address.
addressoverride	This specifies that you will ship only to the address Interchange has on file (including the customer's name and email address). Your customer needs to log into Interchange first - before going to PayPal

Other options are also settable.

Troubleshooting

Try the instructions above, then enable test mode. A test order should complete.

Disable test mode and then test in various PaypalExpress error modes by using the credit card number "4222 2222 2222 2222".

Then try a sale with card number "4111 1111 1111 1111" and a valid expiration date. The sale should be denied, and the reason should be in [data session payment_error].

If nothing works:

Make sure you Required the module in interchange.cfg:

Require module Vend::Payment::PaypalExpress
Make sure Crypt::SSLeay the other prerequisites are installed and working. You can test to see whether your Perl thinks that they are with the following command, adjusted for each of the prerequisite modules:

perl -MNet::SSLeay -le 'print "Available"'

If the above prints "Available", and returns to the shell prompt, for all of the prerequisite modules, then you should be OK (presuming they are in working order otherwise).

Check the local and global error log files.
Make sure you set your payment parameters properly.
Try an order, then put this code in a page:

<pre>
[calcn]
my $string = $Tag->uneval({ ref => $Session->{payment_result} });

$string =~ s/{/{\n/;
$string =~ s/,/,\n/g;

return $string;
[/calcn]
</pre>

That should show what happened.
If all else fails, consultants are available to help with integration for a fee.

Notes

There is actually nothing in Vend::Payment::PaypalExpress; This module changes its package name to Vend::Payment and places things there.

Authors

Lyn St George
Based on original code by Mike Heins