This article describes how payment providers are implemented in Litium Studio. As a developer you will only need to be concerned about this, only if you are going to change a payment provider to implement additional functionality, or going to write a new payment provider.
The Payment Providers provide the functionality to collect payments from the customers account. There are two basic models of collecting payments from a customer. In Litium studio we call them Payment Mode. Payment Mode can be
- One Phased: The money is directly collected from customers account. This is the Payment mode "Charge"
- Two Phased: The money is first reserved from customers account in first instance. Then, later, money is collected from it. This is the payment mode "Reserve"
Payment Method
This is the method of payment such as Credit cards, Bank Direct Debit, Invoice, etc. Various payment providers support various payment methods.
For a full list of payment methods supported, please see here.
Communication
The communication between Litium Studio and Payment Provider will depend on the specific technology used by the respective payment provider. As at 2012 March November, the payment providers are using following technologies, and this may change!.
- PayEx: Web services
- Auriga (Nets): HTTP Post & Web Services (limited support in Web Services)
- Kreditor: XmlRpc
- Dibs: HTTP post
- PayPal: NVP (paypal specific)
- Direct Pay: Not relevant, as this is internal
- HandelsbankenFinans: Web services
Blocking vs Non-Blocking calls
As a developer, it is important that you understands when the payment provider is going to return control back to you when a method is called, or if at all it is going to return in the method you called. In this respect, communication between Litium Studio and Payment Provider is either Blocking or Non-blocking, based on the situation and provider. We will explore in which situations a non-blocking call will result under notes below.
- A non-blocking method call is Asynchronous by nature, Litium Studio will transfer the control to Payment provider, and redirect user to payment providers site.
- A blocking method call is Synchronous by nature, Litium Studio will wait for a reply from payment provider, and will have the execution halted till the result comes. The control will remain inside Litium Studio.
Notes:
- For PayEx, the control is redirected to a remote PayEx address to continue checkout flow in Execute Payment implementation of the Checkout Flow Template page. This is a non-blocking call, since it is a redirection. All other calls are web services calls, which are synchrounous, therefore blocking.
- For Auriga, the control is redirected to Auriga, using a HTTP post, in Execute Payment implementation of the checkout flow template page.. This is a non-blocking call, since it is a HTTP post. All other calls are web services calls, which are synchrounous, therefore blocking.
- For Paypal, the control is redirected to Paypal, using a HTTP post, in Execute Payment implementation of the checkout flow template page.. This is a non-blocking call, since it is a HTTP post. All other calls are synchrounous, therefore blocking.
- All calls to Kreditor is blocking, because each call is a synchronous XML RPC request.
- All calls to Dibs provider a non-blocking, because each call is a HTTP post.
Implementation
The payment providers are implemented using the plugin architecture, with a common interface for all payment providers. So, each payment provider implements the IPaymentProvider interface.
Additionaly, the payment provider is an extension of the PaymentInfo entity object. For this reason, each payment provider must inherit from the PaymentProviderBase base class.
All payment provider functionality is abstracted into the IPaymentProvider interface. Therefore, treatement of all payment providers inside Litium Studio is uniform.
This greatly simplifies how you would use payment providers in your checkout flow, because you do not need to consider about the specific payment provider when using it, you only need to use the IPaymentProvider interface.
Invoking IPaymentInterface methods
The individual payment providers should not be instantiated from your code. Instead, always use the instance attached to the PaymentInfo entity object of the Order entity object. Following example shows invoking the CompletePayment() method of a payment provider.
/// <summary>
/// Called when delivery is confirmed.
/// </summary>
/// <param name="carrier">The carrier.</param>
/// <param name="state">The state.</param>
/// <param name="token">The token.</param>
protected virtual void OnDeliveryConfirmation(DeliveryCarrier carrier,
State<DeliveryCarrier> state, SecurityToken token)
{
//NOTE: we take the order and call the CompletePayment method using
// IPaymentProvider interface.
Order order = ModuleECommerce.Instance.Orders.GetOrder(carrier.OrderID, token);
if (order != null)
{
PaymentInfo paymentInfo = order.PaymentInfo[0];
if (paymentInfo.PaymentProvider.CanCompleteCurrentTransaction)
{
paymentInfo.PaymentProvider.CompletePayment(null, token);
}
}
}