Develop a payment provider
This article describes how to develop your own payment provider
Developing your own payment provider invoves following steps. The links to the bottom of the page has more detailed explanations, while this page contains a summary of the tasks to do.
Implementing IPaymentProvider interface
- Create a visual studio project and add references to Litium.Studio, Litium.Foundation and Litium.Owin dlls.
- Implement the interface Litium.Foundation.Modules.ECommerce.Plugins.Interfaces.IPaymentProvider in class. This class should also inherit from Litium.Foundation.Modules.ECommerce.Plugins.PaymentProviderBase class.
- Add "Plugin("yourPluginName") attribute to the class the above class.
- Implement IPaymentArgsCreator interface in another class and apply the "Plugin("yourPluginName") attribute to it as well. Makesure to check the api documentation of IPaymentProvider interface when implementing.
Working with Payment State Machine
It is very important that your implementation set the correct payment states using the payment state machine. Failing to do so will result in incorrect behaviour. Key points to keep in mind are,
- Before you contact the payment provider for the Authorization call, you need to set the payment status appropriately to either ExecuteReserve or ExecuteCharge depending on whether you use two phase mode or one phase mode. You will set this payment status in the ExecutePayment method of your IPaymentProvider implementation.
- When you get the response back from the payment provider to the OnProviderCallback, depending on the result, set the payment status to Reserved, ReserveFailed, ChargeFailed or Paid.
- For a already reserved transaction, (in the CompletePayment method implementation) before you call the payment provider to charge the account, put the payment status to ExecuteCapture, and when the response is received put to either CaptureFailed or Paid.
- Check how each method is implemented in default implementation for a more better understanding.
Developing the admin panel for the payment provider
AdminPanel of the payment provider is shown to the backoffice user, when a order is placed from the backoffice. One example is Klarna (Kreditor) where customers Social Security Number is additionaly needed to complete the payment. In this case, Klarna's admin panel is shown in backoffice, if you initiate a Klarna payment there.
The path to the AdminPanel should be returned in the AdminPanel property of the IPaymentProvider interface implementation.
Usually the locaiton for admin panel is "~/Site/ECommerce/PaymentProviders/". Take a look at existing admin panels to get an idea of how to program it. An easy option would be to copy one and change to match your payment provier.
PaymentArgsCreator class
You need a class that implements IPaymentArgsCreator interface, and this class should have the Plugins attribute.
Purpose of this class is to convert the CheckoutFlowInfo parameters to ExecutePaymentArgs parameters. Since the payment provider is not aware of the checkout flow and is independent from it, the ExecutePayment method of IPaymentProvider interface receives this ExecutePaymentArgs, instead of CheckoutFlowInfo.
In case you have specific info to be passed into the payment provider, extend the CheckoutFlowInfo class to provide this information.
Changing Web.config to remove a payment provider
The payment providers are recognized by the IoC implementation of Litium Studio and are automatically loaded. If some payment provider is not desired, you may simply delete its .dll file from the bin directory.
The first step in creating a payment provider plugin is to implement the IPaymentProviderInterface and extend the PaymentProviderBase class. This article shows how to create the skeleton, and subsequent articles explain how to fill in the code.
This article explains how to implement the IPaymentArgsCreator interface, which converts the CheckoutFlowInfo into ExecutePaymentArgs.
This article explains function and give guidelines on implementing the IPaymentProvider.ExecutePayment method.
This article explains the functionality and guidelines on implementing the CompletePayment method, which completes a payment in "Reserve mode".
This section explains how AdminPanel of the payment provider is implemented. It is shown to the backoffice user, when a order is placed from the backoffice. One example is Klarna (Kreditor) where customers Social Security Number is additionaly needed to complete the payment. In this case, Klarna's admin panel is shown in backoffice, if you initiate a Klarna payment there.
If there are no user interface to show, still the Admin panel need to be made, but in which case will be made not to be visible.
This article explains how to do a HTTP post into the payment providers website checkout flow page during the ExecutePayment step. The payment provider collects end customers credit card information using their own web page. Litium studio need to re-direct the end customer to this page, so the credit card information can be collected and the payment provider can approve the payment and redirect control back to Litium Studio.
It also explains the implementation of IPaymentArgsCreator interface and extending ExecutePaymentArgs class.
When the control is transferred to the payment providers site, end customer enters his credit card information and confirms the purchase. Then the payment provider will return the control back to Litium Studio by redirecting to the responseUrl (or Cancel url if user cancelled). These urls are given to the payment provider in a previous initialization call, or when the HTTP post to the provider site is done.
This article explains how to handle this payment provider callback.
When this interface is implemented, it is possible for the payment provider to send asynchronous status updates to Litium Studio.
This article explains how to implement this interface and how to receive status updates from the payment provider.
Some payment providers allow to fetch the payment status of current orders from the payment provider server. In a situation where the payment provider has updated the payment status, but has not notified it back to Litium Studio (through IPaymentProviderReport callback), still the payment status can be synchronized by clicking the Synchronize button in payments grid, in Litium Studio backoffice.
Specially in case of Invoice payment methods, the payment provider usually allow the invoice to be downloadable from their website in a .pdf file format when the invoice is active. Such links can be displayed in Litium Studio backoffice, in View Payment and View Order (under payment section) pages. This article shows how to implement this functionality.
In the Litium Studio backoffice, in the Payments grid, four command buttons are available to execute Reserve, Charge, Cancel or Return operations on the selected payment. However, certain payment methods might not allow some of these operations. For example, a bank direct payment might not support "Reserve" operation, and an invoice method might not support "Return" operation.
This article shows how to enable or disable these buttons from the payment provider implementation logic.
When the payment mode "Reserve" is used, a reserved transaction can be cancelled at the payment provider. This article explains how to implement the Cancel operation.
Once a payment is completed, it is possible to refund the money back to the customer, usually if the order is returned. Refunding a payment may be possible only in certain payment methods depending on the payment provider.
This article shows how to implement it in the payment provider plugin.