uCommerce includes full API reference documentation and lots of helpful articles to help you build your e-commerce site as effortlessly as possible.
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.
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.
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.
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.
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
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
The “IPaymentWindow” represents a class that is able to render a page to the Response or to handle a callback from payment gateways.
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.
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.
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.
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.
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”.
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:
The '/' is used as the spilt character, so only the imagination will limit you here.
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.
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.