Integrating with a Payment Gateway using External Payment Windows

The Challenge

In some scenarios you want to leave payment processing almost entirely up the remote payment gateway to avoid having to raise the PCI compliance level of your solution. The challenge then becomes to put in place infrastructure to handle the interactions between your server and the payment gateway server both when redirecting the customer to the payment gateway and handling any return traffic from the payment gateway to your server.

Basically the customer is redirected to the payment gateway to enter credit card information and is redirected back to your server once the process is done. Meanwhile the payment gateway will in some cases perform a callback to your server as well to notify you about the status of the payment.

Purchase Flow

These steps will be executed during the payment processing flow. Authorizations, captures, refunds, and voids (cancellation of a payment) are handled by the gateway. Follow the yellow boxes in the picture above.

1. User arrives at the Store and gets a basket assigned.
2. The user adds different products to the basket.
3. User checks out and confirms the basket content.
4. User types in buyer information (email, address, name, etc.).
5. User selects a payment provider, e.g. PayPal, SagePay, WorldPay, PayEx, Payer.se, DIBS, or ePay.
6. Process Payment will either result in a local store flow or a remote payment gateway flow. See the 2 different flows below. The only real difference is how the implementation of the request payment is done.
7. The user gets directed to a form, which makes an auto postback with Javascript to the gateway with all the required information. This information might be the amount, key, order number, and more depending on the gateway.
8. User chooses type of credit card.
9. User types in credit card information.
10. The payment gateway validates the information. When valid, it will make an asynchronous or synchronous callback back to the shop’s PaymentProcessor.axd (See the description of the class later in this guide). Depending on the payment gateway it will automatically redirect you back to the shop or present you with a “return to shop” button; you can click if you want to return to the shop, to get a receipt.
11. The user gets an order receipt, optionally CC via email.

The Solution

To solve the problem of the customer leaving the store server to authorize credit cards an extended framework for handling payments is needed, which is used to accomplish the interaction between server in a structured and simple way.

This is a two-step process:

We need to prepare the data to be sent to the payment gateway and then redirect or post that information to the gateway thus handing over the user to the gateway. Second we need to intercept the callback, so we can mark the payment as completed. If that was the last payment in a series the entire order needs to be marked as completed, usually by executing the checkout pipeline.

Payment Window Framework Explained

The IPaymentWindow is the main interface implemented to support the server to server interaction. It’s implemented by the class ExternalPaymentMethodService, which contains the methods for requesting payments, “RequestPayment”, which will redirect the customer to PaymentRequestForm which in turn redirect the customer to the payment gateway supported by the particular payment method service.

Passing the Customer to the Payment Gateway

Passing the Customer from the Payment Gateway

PaymentRequestForm

This class implements the IHttpHandler interface. In a default Ucommerce installation its set up by default to intercept calls made to “PaymentRequest.axd”.

What it does

• Tries to extract payment information from the URL using the PaymentUrlInformation helper class.
• From the payment information it will try to find the payment in the system.
• It will then lookup the payment method service assigned to the payment.
• Cast the payment method service to an IPaymentWindow.
• Calls RenderPage method on the IPaymentWindow instance just found.

PaymentProcessor

This class also implements the IHttpHandler interface. In a default Ucommerce installation it’s set up by default to intercept calls made to “PaymentProcessor.axd”.

As PaymentProcessor is exposed as an HTTP endpoint it is important that all data it receives is validated. For many payment gateways this is done using MD5 hashes of the values passed to the gateway and back or two-encryption as is the case with PayPal.

What is does

• Tries to extract payment information from the URL using the PaymentUrlInformation helper class.
• From the payment information it will try to find the payment in the system, which has the status marked as “PendingAuthorization”.
• It will look up the payment method service used to request this payment as passed in the URL.
• Casts the payment method service to an “IPaymentWindow”.
• Calls method ProcessCallback on the IPaymentWindow instance with the payment found earlier as the parameter.

IPaymentWindow

The “IPaymentWindow” represents a class that is able to render a page to the Response or to handle a callback from payment gateways.

Methods

• RenderPage – This method should return a HTML page and return it. The page rendered will usually contain the HTML form, which needs to be posted to the payment gateway to initiate the payment processing flow on the remote end. It can however be used to redirect the user to another URL also. In these cases it will return an empty string.
• ProcessCallback – This is called from the PaymentProcessor class and handles logic involved when a callback arrives. That could be getting the transaction id, setting the payment status as authorized, things like that.

IPaymentMethosService

Interface for implementing a Payment Method Service for payment processing. This interface is part of the ExternalPaymentMethodService. The IPaymentMethod service is documented in detail elsewhere, but holds the most basic interface for doing payment gateway integration like RequestPayment, AcquirePayment, Cancel, and Refund.

AbstractPageBuilder

This is an abstract base class for building a HTML page as most payment gateways expect a form POST to pass information to the service; this class eases the implementation.

Methods

• BuildBody – Here goes all the HTML elements inside the tag, this is usually the form elements to represent the data.
• BuildHead – Here goes all the HTML elements inside the tag. This is in most cases just used to put some javascript to make the form autosubmit.

What it does

When Build is called it will return the HTML page with the html, head, and body tag and all the custom tags that were added in the two abstract methods BuildHead and BuildBody.

ExternalPaymentMethodService

This is the base class when implementing an external payment gateway. Since this class implements the IPaymentWindow, you also need ProcessCallback and RenderPage. See the IPaymentWindow for a description.

Abstract methods

There are three methods that are required to be implemented. Acquire, Refund, and Cancel payment, if the gateway supports it. These are suffixed with internal, because they are protected and are only used by the base class “ExternalPaymentMethodService”.

• AcquirePaymentInternal
• CancelPaymentInternal
• RefundPaymentInternal

Helper classes

PaymentUrlInformation

Class used when extracting payment information from a URL. This is primarily used by PaymentRequestForm and PaymentProcessor. It extracts information from the HttpRequest instance provided to the “ExtractInformation” method.

The method expects the URL to be in the following format:

• http://yoursite.com/{somedir}/{someotherdir}/{PaymentMethodName}/{PaymentId}/file.axd
• http://yoursite.com/{PaymentMethodName}/{PaymentId}/otherfile.axd

The '/' is used as the spilt character, so only the imagination will limit you here.

AbstractMd5Computer

Abstract base class used when working with MD5 hashes. It contains one method to compute a hash from a string usually to validate information sent to the payment gateway and receive back on the local server to ensure that the values aren’t tampered with.

All there is left to do is register the new payment method service as a component by adding a new file to Ucommerce/Apps/MyApp called Payment.config:

    
    <configuration>
    	<components>
    		<component 
    			id="MyPaymentMethodService"
    			service="UCommerce.Transactions.Payments.IPaymentMethodService, UCommerce"
    			type="MyApp.MyPaymentMethodService, MyApp" />
    	</components>
    </configuration>
    

Please refer to Register a Component if you're interested in more details about components.

Summary

With the Payment Window Framework you have a nice way of creating the server to server interaction without having to do the supporting pieces yourself.

More importantly the framework is used in a number of the payment providers supplied with Ucommerce out of the box like PayPal, SagePay, RBSWorldPay, PayEx, DIBS, ePay, and Payer.se.