In the first part, we touched on the basics of the WordPress HTTP API and how to make a simple GET request and read the response. In this tutorial, we'll learn about the PayPal Express Checkout API and how to build a class that uses the HTTP API to process payments with PayPal. Preferably, you will have some knowledge of what PayPal is and also a Sandbox account (which is free and easy to get). We've done this as a plugin to show how the PayPal class works and ease making the HTTP requests.

An Overview of the PayPal API

PayPal is an online payment processor. It's quite popular, and enables millions of professionals and businesses to exchange money online with just an email address. You may even already be using PayPal to receive payments from clients. Clients login to their PayPal account and send the money to your PayPal account using your email address.

This is good for personal and manual money sending. Businesses, however, need to automate the process. They usually setup a shopping cart where purchasers add items and then complete the purchase by entering their shipping details and payment information.

The PayPal team have put various procedures to automate payments. They are confusing at times; and to be honest, their documentation is a little messy. I have picked the Express CheckOut API for two reasons: It's quite simple and straightforward to implement; and it enables a very good degree of customization.

The Express Checkout Flow

The payment process begins from your website. After putting some items in their shopping cart, your visitor goes to the shopping cart page where they find the items they added and the total amount. You should also include the PayPal payment button.

When the user clicks the PayPal payment button, they get redirected to the PayPal login page. They need to enter their login details, and confirm the purchase. The PayPal login and confirmation page can be customized (by adding the order details and total amount to be paid) but it's optional. After confirming the payment, the user is returned to your website to a web page that you specify.

When the user is returned to your page, you complete the purchase order. First, you execute the payment order (charge the buyer's PayPal account), and when the transaction succeeds, you redirect the user to your product download page, or you notify your shipping department of the order.

What Does It Have to Do With HTTP?

Although it may not look like it, most of the stuff actually happens on your website and servers. To redirect the user to the PayPal page, you need first to get a "Token" key from PayPal. To get this key, you need to send a POST request to the PayPal Server API with your account and transaction details. If the request succeeds, PayPal will answer with a "Token" key.

When the user logs in to his PayPal account and confirms the payment, the payment isn't actually processed. In this step, the user only grants the right for your service to process the transaction. After the authorization, the buyer is returned to your website where you can complete the process and charge the user.

At least, you'll have two HTTP requests. The first one is to get the "Token" which you'll use to redirect the user to the payment page. The second is to complete processing the payment for the buyer. You can do additional requests before completing the payment in which you request the payer details (like the Shipping address), but it is optional.

The PayPal Gateway Class

To standardize and streamline the process, I have coded a PHP class which does the required requests by simply giving it the parameters. The class implements the 3 request methods supported by the PayPal API:

setExpressCheckout – This request returns a "Token" key which will be used to redirect the user to a login page.

getExpressCheckout – Use this request to get information about your buyer, like the shipping address or the payment status.

doExpressCheckout – This request completes the payment and charges the user account.

These methods require some common parameters like the PayPal API version, your account username, password and also a signature. If you haven't already, sign up for the PayPal Sandbox which is a test platform that emulates the real PayPal. Our class will support the sandbox environment.

Making the HTTP Request

For the 3 methods mentioned above, I have found out that they share a good amount of code. They basically do the same request, but use different parameters for each.

Request type: POST

Request URL: The PayPal API server or the Sandbox PayPal API server

Timeout: 60 (a short timeout might result in an unsuccessful request)

SSL Verification: Default to false if the "https_local_ssl_verify" is not set

Request body: different from one method to another.

Using the Class

First, you'll need to have an idea about the required parameters. I'm going to summarize them here, but for more extensive and complete details, check out the PayPal Express Checkout documentation. The following table tries to summarize the required parameters for successful set, get and do requests.

The Class Code

Step 1 The Class, Properties, and Methods

We start off with a class skeleton defining the properties, the constructor and the different methods. Each property and method is preceded with a comment section that has a description, the accepted parameters and the returned variable. The comments follow the PhpDoc guidelines.

Step 2 The Constructor

The constructor initiates a new instance of our class. It accepts one parameter which enables the sandbox mode if you pass "true" to it. The method will set the Server and Redirect URL following the sandbox argument. It'll also set the SSL Verify property applying the "https_local_ssl_verify" filter.

Step 3 The Request Method

The class implements the 3 request methods as specified by the PayPal API: setExpressCheckout, getExpressCheckout, and doExpressCheckout. The common thing about these 3 functions is that they all do a POST request to the PayPal server.

To keep our code DRY, I have created a single function to make the other 3 helper functions that call our main function and specify the type of the request.

If our request is successful, the function will return "true" and save the request response to the "full_response" property. If our request fails for whatever reason, the function will return "false" and saves information about the error in the "debug_info" property.

Step 4 Utilities Functions

Our class makes use of two utility functions. The first function replaces the long PayPal parameters with short names. So instead of using "PAYMENTREQUEST_0_AMT" as your input key, you just put "amount"; a less cryptic and easier to remember word.

Step 5 The Response Methods

The request methods return the full, unaltered response. That's where our response methods come in handy. If the request is successful, PayPal will return the response in a URL like encoded string. The helper functions will decode and return only the required part and in a more accessible format.

getResponse – Returns an array of key/value pairs containing the full PayPal response.

The PayPal Test Plugin

To make the debugging and testing of the PHP class easier, I have created a WordPress plugin which offers a simple interface. You enter the required parameters for each type of the request, and you click the send button. The request will be processed with AJAX, no page reload is required. The request results will be displayed on the right of the forms.

The Plugin Code

The test plugin is made up of two components: The front-end which is a set of input boxes and the second is the back-end which handles the AJAX requests submitted by the plugin front-end.

Each request has common settings which are the same on every request, and specific settings which depends on its type. The front-end references the input boxes value, and groups them on objects. It also adds a click handler for every button which does a simple jQuery post request to the "ajaxurl" with the specified input.

The test plugin doesn't do any checking on the input. So make sure you are typing the correct parameters.

On the back-end, the AJAX requests are handled using the "wp_ajax_" action. The function associated with the action will evaluate the global "$_POST" variable and create a new instance of the PayPal class.

If the ExpressCheckout request is successful, the full response is returned; otherwise, the debugging information will be returned.

Conclusion

In this tutorial, we learned some basics about the PayPal Express Checkout API; and also explored how to build a payment gateway class using the WordPress HTTP API. Now you can use this class to easily implement PayPal payments in your plugin.

In the next and final article in the series, we'll learn how to build a self-hosted plugin repository to enable automatic updates for plugins which are not hosted in the WordPress Plugins repository.