Accepting Credit Card Payments with OXID eShop CE and AlertPay

A New Direction

In a previous article, I introduced the OXID eShop CE open-source shopping cart system and illustrated how it could be extended to accept credit card payments from customers using the Authorize.Net payment gateway. The technique I illustrated in that article made use of OXID eShop’s existing checkout mechanism to request credit card information from the user, transfer this information to Authorize.Net through a secure POST request, and integrate the result into OXID eShop’s transaction flow.

A payment gateway that offers this kind of transaction-oriented API is generally preferred, because it allows a greater degree of control over the transaction, and doesn’t require the user to visit a third-party site to enter payment information. However, many payment gateways require the shopping cart to transfer control to their own user interface in order to enter payment information, and then return control to the shopping cart once the transaction is complete. You can still use OXID eShop with such a payment gateway – the software is flexible enough to accommodate a number of different transaction flows – but doing so requires a different approach from that shown earlier.

Over the next couple of pages, I’ll discuss this in detail, showing you how to create an OXID eShop module to accept credit card payments via the AlertPay payment service. Unlike Authorize.Net, this service requires users to visit and enter credit card information into a third-party Web site. As such, integrating it with OXID eShop is somewhat more complex, but it can be done. Come on in, and find out how.

Putting The Pieces Together

If you’re tuning in late, OXID eShop CE is a modular, standards-compliant shopping cart system. Developed using PHP and MySQL and maintained by OXID eSales AG of Germany, OXID eShop CE includes support for common functions such as displaying products, managing inventory and orders, collecting user reviews and searching product catalogs. It’s free for both commercial and personal use under the GNU General Public License. This article assumes that you already have OXID eShop CE v4.1.2 installed and working – in case you don’t, you can find the latest release, installation instructions and a quickstart guide on the OXID eShop Web site.

Although OXID eShop doesn’t support any particular payment gateway out of the box, its basic framework can be easily extended to support your payment gateway of choice. This article uses the AlertPay payment gateway, which is popular with merchants because of its friendly interface, support for both one-time and recurring payments, automatic payment notifications and free sample code for many different programming languages. Unlike Authorize.Net, AlertPay doesn’t allow applications to make remote procedure calls for credit card authorization; instead, to perform a credit card payment, users must visit the AlertPay Web site and input the necessary information into an AlertPay form. Once the transaction is complete, the AlertPay Web site automatically redirects the user back to the source application.

The remainder of this article assumes that you have developer access to the AlertPay service; to obtain this access, drop by the AlertPay Web site and request a free developer account. Account credentials include a login ID and a transaction key; you’ll need these to gain access to the payment gateway and perform test transactions, so hold on to them tight. While you’re there, it’s also a good idea to download the AlertPay Merchant Integration Guide. This guide provides detailed information on AlertPay’s advanced integration options on different platforms, and includes specifics on the parameters required when transferring control between a Web application and the AlertPay service.

GET It Right

Performing a payment transaction with AlertPay is pretty simple: you need to submit a GET request to the specified payment gateway URL containing basic transaction information, including account credentials, the transaction amount, and a descriptive label for the transaction. Here’s an example of one such request:

Here’s a quick explanation of these fields (for details, refer to the AlertPay Merchant Integration Guide):

  • The ‘ap_purchasetype’ field indicates the type of item being purchased. Possible values include ‘item’, ‘service’, ‘item-goods’ and ‘item-auction’.
  • The ‘ap_merchant’ field provides the merchant’s login name on AlertPay.
  • The ‘ap_currency’, ‘ap_quantity’, ‘ap_amount’, ‘ap_itemname’ and ‘ap_description’ fields contain information on the transaction currency, item quantity, item per-unit price, item name and item description respectively.
  • The ‘ap_returnurl’ field contains the URL to which AlertPay should redirect after the transaction is complete. Although AlertPay does not officially support URL parameters, you can pass a single parameter on this URL.
  • The ‘ap_cancelurl’ field contains the URL to which AlertPay should redirect if the transaction fails or is cancelled by the user. Here too, a single parameter is supported (although not officially).

In response to this GET request, AlertPay will generate a customized Web form authenticating the seller and inviting the user to enter credit card information to complete the transaction. Here’s an example of what this form looks like:

The user can choose to either complete or cancel the payment transaction. If the user chooses to complete the transaction, AlertPay will process the transaction and then return the user to the source application using the URL specified in the $_GET['ap_returnurl'] variable. If the user chooses to cancel, AlertPay will return the user to the source application using the URL specified in the $_GET['ap_cancelurl'] variable.

Pay and Play

Now, if you look at the OXID eShop checkout process, you’ll see that the third step in the process requires the user to select a payment option. The default payment options included with OXID eShop CE are direct debit, COD and credit card, as shown below.

As a necessary first step, you must add AlertPay to this list. This is easily accomplished, as OXID eShop CE’s administration module allows shop administrators to add any number of payment providers to the system. A rules-based system also gives administrators precise control over which providers should be made available for a particular combination of user type, country and shipment method. This makes it possible to, say, allow users requesting standard shipping in Germany to make COD payments but only permitting users requesting priority shipping in Canada and the USA to make payments via bank transfer or AlertPay.

To add AlertPay to OXID eShop CE, visit the OXID eShop CE administration panel, usually at http://your-oxid-domain/admin/, navigate your way to Shop Settings -> Payment Methods -> Create new Payment Method and add an entry for AlertPay to it, as shown below:

When you do this, OXID eShop will update its oxpayments table with a record for the new payment method and assign it a unique identifier. This identifier is usually a hashed string that’s not particularly easy to remember. Since we’ll be keying certain methods on it, it’s a good idea to change it to something more readable. Do this by dropping to your MySQL command prompt and running the following commands:

You should also visit Shop Settings -> Shipping Methods -> Payment -> Assign Payment Methods and link the new payment method to the existing shipping methods, countries and user groups. Here’s what it looks like:

Once you’ve performed these tasks, AlertPay should show up as a payment option in the third step of the checkout process, as shown below:

Back To Class

When the user submits an order through OXID eShope CE, the Order view generates a new oxOrder object, calls a number of methods related to order finalization and then, depending on the results, either displays a success notification or redirects the client back to the Payment view for re-entry of payment information.

Here’s a flow chart of the execution chain:

It should be clear from the above flow chart that the easiest way to transfer users to the AlertPay web interface is to extend the base Order object and splice new redirection code into its _getNextStep() method (this is also the method recommended by the OXID development team).

The first step is to extend the base order management class, Order, and override the parent class’ _getNextStep() method, as in the following empty class definition:

OXID eShop expects custom classes and modules to be stored in subdirectories of the $OXID/modules directory, where $OXID refers to the main OXID installation directory. With this in mind, save the above class definition to $OXID/modules/alertpay/alertpay_order.php.

Notice also that this custom AlertPay_Order class, instead of extending the Order class, actually extends a “virtual” class named AlertPay_Order_parent. This is the recommended method of extending OXID eShop core classes, as it makes it possible for multiple modules to use the same class; the virtual *_parent class is automatically created by the OXID framework.

Now, let’s fill the AlertPay_Order class with some code. Begin by adding some properties to reflect account credentials, remembering to update them with your own details:

Then, load the current order into an oxOrder object and check that the payment method was AlertPay, keying against the unique payment identifier that you earlier added to the oxpayments table. This is also a good time to collect some additional order information, such as the currency and transaction amount:

Create an array of data that matches the input expected by AlertPay, and build a GET request from it. Then, redirect the client to that URL:

Once the user has finished with AlertPay, AlertPay will redirect the client back to either the 'ap_cancelurl' or the 'ap_returnurl'. These URLs correspond to two new public methods, processAlertPayCancel() and processAlertPayReturn() respectively, which internally set a status variable and then call the _getNextStep() method to either delete the order from the database, or update its status and send the user an order confirmation email.

Here’s the complete class definition for your reference:

You’ve Got Mail!

The code in the previous section handles most of the heavy lifting, but there’s still one glitch. Look at the chain of events that occurs when a user submits an order, and you’ll realize that one of the operations includes sending the user an order confirmation email. This flow isn’t ideal when working with AlertPay; what you really need is to alter the chain of events so that the order confirmation is sent after the user completes the transaction on AlertPay and not before.

With this in mind, create a new class, this one extending the oxOrder class and overriding the default _sendOrderByEmail() method with a new one that includes an exception for AlertPay transactions, as below:

Save this class as $OXID/modules/alertpay/alertpay_oxorder.php.

The change to the sendOrderByEmail() method ensures that order confirmation emails are not sent out when an AlertPay order is submitted. Instead, the order confirmation is emailed later, through the sendAlertPayOrderByEmail() method, once AlertPay transfers control back to OXID eShop via the processAlertPayReturn() and _getNextStep() methods.

To link these custom child classes to their parents, log in to the OXID eShop administration panel, navigate your way to Master Settings -> Core Settings -> System -> Modules and add the following entries to it:

Here’s what it looks like:

Speaking SEO

All that’s left now is to map the cancel and return URLs to the processAlertPayCancel() and processAlertPayReturn() methods respectively. This is simpler than it sounds, because OXID eShop comes with a sophisticated SEO implementation that makes it possible to create static URLs that internally map to particular classes and methods.

When the OXID eShop front controller received a request for an SEO-compliant URLs, it internally invokes a URL decoder, which remaps the request to the appropriate shop controller and passes it the parameters necessary to generate the correct product or category view. The mapping between the SEO URL and the corresponding internal URL is maintained in the oxseo database table, which looks something like this:

You can add two new URLs to this list, by visiting the OXID administration panel, navigating to Master Settings -> Core Settings -> SEO -> Static URLs and entering the following values:

Here’s what it looks like:

This mapping ensures that when AlertPay redirects the client to http://your-oxid-domain/ap-return-en/, OXID will automatically translate that URL to http://your-oxid-domain/index.php?cl=order&fnc=processAlertPayReturn, thereby invoking the processAlertPayReturn() method discussed earlier and setting in motion the code that updates the order status and sends out the confirmation email. Similarly, if the user cancels the AlertPay transaction and AlertPay redirects the client to http://your-oxid-domain/ap-cancel-en/, OXID will automatically translate that URL to http://your-oxid-domain/index.php?cl=order&fnc=processAlertPayCancel and invoke the code to delete the order from the database.

To try it out, add some items to your shopping cart and head for checkout. Once you submit your order, OXID eShop should redirect you to the AlertPay Web site, where you can enter credit card information. Once the transaction is processed on AlertPay, you should be redirected back to OXID eShop and shown an order confirmation page, as below:

In the event the transaction fails or you cancel it manually, you’ll be redirected back to the payment selection view and an error string will be displayed in this view, as below:

And that’s about it. As this article illustrates, even if you’re working with a payment gateway that doesn’t offer a remote interface to its transaction system, you can still use OXID eShop’s extensible, object-oriented architecture to rejigger the default transaction flow and get things working just right. Play with it yourself sometime and see what you think!

Copyright OXID eSales, 2009.