The Bakery Everything CakePHP

Index

1. Introduction
2. Usage Examples
3. Feedback
4. The Paypal Component

Introduction

While building a large CakePHP based application I found myself needing to integrate PayPal Direct Payment API with CakePHP. For those of you who don't know this API here's a short statement from PayPal's website describing its main objective:

Direct Payment API offers you direct credit card payment processing capability through PayPal. For credit card transactions, customers stay on your website as PayPal processes the payment in the background.

Now, I have built PayPal Direct Payment API applications in the past, but I wanted to bake paypal the proper cakish way. Furthermore, as PayPal's TOS states, PayPal's business rules require that sites that offer Direct Payment API (credit card processing without leaving your website) also must offer Express Checkout Payment (where buyer gets transferred to PayPal's website to confirm the order and then taken back to your website.) It is a bummer, but it is mandatory.

It is also important to know that only people with bank accounts in the US can apply for Website Payments Pro (the PayPal service that allows you to use Direct Payment API.) While this may discourage some bakers from even trying the API, you should now that PayPal offers a Sandbox environment to allow you to test every aspect of the integration.

For that purpose I've created a CakePHP component that provides a wrapper for PayPal's Direct Payment API. I have tested it with CakePHP 1.1.10.3825 running on:

1. Apache 2, Windows XP, PHP 4.4.4
2. Apache 2, Debian Linux, PHP 5.2.0

Pre-requisites

PEAR and PayPal Direct Payment API

You'll obviously need PayPal's Direct Payment API for PHP. You can get it at:

https://www.paypal.com/IntegrationCenter/ic_sdk-resource.html

It is a PEAR based package so needless to say PEAR's core must be included on the vendors path. It is up to you how you install the API on your cake environment. This is what I've done:

1. Downloaded PEAR base from http://pear.php.net/package/PEAR
2. Unzipped PEAR based to {CAKE}/app/vendors/PEAR
3. Downloaded PayPal Direct Payment SDK from https://www.paypal.com/IntegrationCenter/ic_sdk-resource.html
4. Unzipped directory php-sdk/lib in SDK's zip to {CAKE}/app/vendors/PEAR
5. Created a pear.inc.php file on {CAKE}/app/vendors with following content: Download code // Set path to PEAR files

define('PEAR_PATH', dirname(__FILE__) . DS . 'PEAR');

// Add PEAR path to library path

set_include_path(PEAR_PATH . PATH_SEPARATOR . get_include_path());
6. Added following line to {CAKE}/app/config/bootstrap.php: Download code vendor('pear.inc');

Set up a PayPal Sandbox account

Can't really go through the whole explanation, but follow instructions on https://www.paypal.com/IntegrationCenter/ic_sandbox.html

Important Notes

There are two ways to make a payment: through Direct Payment API and via Express Checkout.

The Direct Payment API takes mandatory information such as order amount, credit card info, and shipping addresses to process the order by contacting PayPal's server via SOAP messages. When it is done, you either get a succesfull code (meaning that the sale was made) or an error. Therefore, it is a one-time call to the component. You set up the component's required variables, call directPayment(), and you get the appropiate result.

Unlike the simplicity of Direct Payment API, Express Checkout requires the user to be redirected to PayPal's website to confirm the payment, and then sends a callback to your site sending a Token ID. This callback is a way for PayPal to give us this ID that we will need when we want it to process the order. This means that you will need to call expressCheckout() function inside the component twice: when you initiate the payment (at which point the user is redirected to paypal) and when you get back the token and want to perform the actual transaction. There's no need to tell the component which token you've got, it will figure out what it's supposed to do when you call expressCheckout().

One very important issue regarding Express Checkout: I have my PayPal payment behind an authenticated action. When testing online I discovered that after paypal's callback to my website Cake's session got lost. Since you can tell the component which will be the URL that will be called when PayPal gives the callback, I added Cake's session ID to the URL. Before the first call to expressCheckout(), the call that makes the redirect to paypal, I store the session information using the component's function:

Download code $this->Paypal->storeSession();

Then, when I get the callback (which I can check because I specify which URL gets called) I restore the session:

Download code if (isset($_REQUEST['csid']))
{
    // Restore session
    
    if (!$this->Paypal->restoreSession($_REQUEST['csid']))
    {
        $this->redirect('/');
        exit;
    }
}