Ecommerce Payment Provider Model

Ecommerce Payment Provider Model

Posted on November 08, 2011 0 Comments

The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.

Sitefinity 4.3 offers a new feature for developers to implement payment processors of their choice using  the “Payment Provider Model”.  Once a developer implements their payment provider, the payment transaction occurs transparently in the background providing a common and easy checkout experience for the customer. There are many payment processors that will fit into this model such as FirstData, Checkout by Amazon, WorldPay, Moneybookers, Linkpoint, Website Payments Pro, etc… The developer will need to contact the payment processor and ask for developer documentation and testing credentials.  The merchant will need to sign up with the payment processor as well.
 
The Payment Provider Model works for payment processors that publish an API using a webservice, XML feed, etc.  This works best for API’s that allow the merchant to transparently submit the transaction where the customer never leaves the store website.  This helps conversions and provides a consistent checkout experience common with online stores. 

We have already used this model in Sitefinity to implement the three payment providers supported namely Authorize.Net AIM, PayPal Payflow Pro and SagePay Direct.  The provider model lets developers implement the payment processor in the “payment methods” section of Sitefinity backend.  It is also possible to implement multiple payment processors where the merchant might want to process a specific credit card through one processor and another credit card through a different processor.  The developer/merchant can decide which payment transactions to implement such as Authorize Only, Authorize and Capture or a Sale.

In the near future Sitefinity will have additional functionality to support payment gateways that require the customer to leave the site, log on the payment site, process the transaction and return to store such as Google Checkout, PayPal Express Checkout , 2Checkout, etc…

For Developers

The remainder of this post is directed to the developer on how to implement the payment provider model.   Thanks to Venkata Koppaka for providing the following information:

Downloads

Payment Provider Model Example
The Payment Provider Model can be split into two parts from a high level:

1. Payment Processor Code
2. Payment Processor Configuration area

You will first need to create the necessary code files.  Once you have completed the code files, and they compile without error, then you can move on to create the configuration area in the Sitefinity backend.

Payment Processor Code

General Overview

This section talks more about the implementation of the custom provider.

All IPaymentProcessorProvider methods take IPaymentRequest as an input parameter and return IPaymentResponse as an output parameter.

By default SubmitTransaction method of the provider will be called with IPaymentRequest object. In SubmitTransaction method you can decide which of the other methods you want to call, be it be a Sale method or Authorize method or any other custom method you might have.

Implementing a Customer Payment Processor within the SitefinityWebApp

Copy the sample files to your SitefinityWebApp folder.  For this example we will create a new folder called “CustomPaymentProcessor” and then copy the following files into that folder:

• CustomProvider.cs: This file should inherit from IPaymentProcessorProvider. This file is where you can write your concrete implementation of the IPaymentProcessorProvider type.

• CustomSettings.cs: This file should inherit from IPaymentSettings. This file is where you define the settings (model) of your custom payment processor.

• CustomSettingsField.ascx: This file controls the HTML that gets rendered in the Payment Method backend screen. You will also define your input areas (textboxes which accept data from the user )

• CustomSettingsField.cs: This file should inherit from FieldControl. This file is where you define what layout and script options you want to use.

• CustomSettingsField.js: This file has the javascript that validates the controls and sends Sitefinity the serialized data that has to be saved in the database.

After you copy all the sample files your solution should look close to the screenshot below –


Next you need to change the “CustomSettingsField.ascx“and “CustomSettingsField.js” files to be Embedded Resources.  Within your Visual Studio solution, right click on the “CustomSettingsField.ascx” file, and select “Properties”.

Change the “Build Action” property to “Embedded Resource”.
Do the same for the “CustomSettingsField.js” file.

From these files you will need three pieces of data that you will use to configure your payment processor in the Sitefinity settings section: The SettingsType, ViewProviderType and ProviderType.

1. For the “SettingsType” setting you need the fully qualified namespace for the CustomSettings class in the CustomSettings.cs file.  For this example:

namespace SitefinityWebApp.CustomPaymentProcessor
{
    public class CustomSettings : IPaymentSettings
    {

Your SettingsType property value is:
SitefinityWebApp.CustomPaymentProcessor.CustomSettings

2. For the “ViewProviderType” setting you need the fully qualified namespace for the CustomSettingsField class in the CustomSettingsField.cs file.  For this example: 

namespace SitefinityWebApp.CustomPaymentProcessor
{
    public class CustomSettingsField : FieldControl
    {

Your ViewProviderType property value is:
SitefinityWebApp.CustomPaymentProcessor.CustomSettingsField

3. For the “ProviderType” setting you need the fully qualified namespace for the CustomProvider class in the CustomProvider.cs file.  For this example:

namespace SitefinityWebApp.CustomPaymentProcessor
{
    public class CustomProvider : IPaymentProcessorProvider
    {

Your ViewProviderType property value is:
SitefinityWebApp.CustomPaymentProcessor.CustomProvider

Creating your Custom Payment Processor Properties

The CustomSettingsField.ascx file contains the markup for the properties displayed to a user who is configuring your payment processor in the Payment method area.  The sample CustomSettingsField.ascx file has the following default fields: 

Field

Description

processorCreditCards

Dropdown control of credit cards that the payment processor can process

processingMode

Determines if the payment processor is set to Live or Test mode

liveUrl

The URL called to process payments when in Live mode

liveUsername

The username needed for payment processing credentials when in Live mode.

livePassword

The password needed for payment processing credentials when in Live mode.

testUrl

The URL called to process payments when in Test mode

testUsername

The username needed for payment processing credentials when in Test mode.

testPassword

The password needed for payment processing credentials when in Test mode.

timeout

Time (in milliseconds) when the payment processing service will timeout

paymentType

Dropdown list of payment types available for the payment processor (Sale, Authorize, Authorize and Capture, etc.)


You may need more or less of the default fields depending on the requirements of your particular payment processor.  For instance, some payment processors may require an “access key” instead of the “username”.  You may add or remove any fields as necessary in the markup file.

If you add or remove any fields from the markup file, you will need to modify the code behind file, “CustomSettingsFields.cs” and the javascript file “CustomSettingsFields.js”.

To get to your settings programmatically (Serialized data of type IPaymentSettings),  You need to cast PaymentProcessorSettings to your own settings type. Below is an example on how to do that for the example –

public IPaymentResponse SubmitTransaction(IPaymentRequest data)
{
     var settings = (CustomSettings)data.PaymentProcessorSettings;

 

Creating your Custom Payment Methods

You next need to create methods for handling payments from your customer processor.

Open the “CustomerProvider.cs” file.  You will see a series of payment method stubs, one method for each type of payment process (Credit, Sale, Authorize, Capture, Void, etc.).

By default SubmitTransaction(IPaymentRequest data) method is called for the provider. In this method you can decide which other payment methods you want to call. Below is an example on how you would do that – 

public IPaymentResponse SubmitTransaction(IPaymentRequest data)
       {
               varsettings = (CustomSettings)data.PaymentProcessorSettings;
           if (settings.PaymentType == "sale")
           {
               return Sale(data);
           }
           else if (settings.PaymentType == "authorize")
           {
               IPaymentResponse paymentResponse = Authorize(data);
               paymentResponse.IsAuthorizeOnlyTransaction = true;
               return paymentResponse;
           }
           else if (settings.PaymentType == "authorizeandcapture")
           {
               return AuthVoidCapture(data);
           }
           
           return new PaymentResponse { IsSuccess = false, GatewayResponse = "Payment transaction type not supported" };
       }

All of the payment methods receive a parameter of type IPaymentRequest which holds most of the payment data you will need to pass to your payment processor.  A few of the payment methods also receive additional parameters with data necessary for that specific payment type.

Every method returns an instance of an IPaymentResponse object.  After calling your payment processor, you will need to parse the results returned from the processor and store those results in an instance of an IPaymentResponse object which your method will return to the calling method.

Payment Processor Configuration Area

The payment processor configuration is at Administration->Settings->Advanced->PaymentProcessor.

To add a new Payment Processor Click on Create New button in the PaymentProcessorProviders area.
You will be presented with the form below:

 

Properties in detail

Id - required

Id is the unique GUID for the payment processor. You can use any unique GUID for this field (Tip: You can use visual studio to generate a new GUID, Tools->Create GUID)

Name - required

Name is the name of the payment processor (examples: AUTHNETAIM, PAYFLOWPRO, SAGEPAY)

Title - required
Friendly name of the payment processor that gets shown throughout the system (examples: Authorize.Net AIM, PayPal PayFlowPro, SagePay)

Description – optional
Description is the full description about the payment processor. This field is optional (examples: SagePay Provider etc...)

IsActive – required
IsActive field decides whether or not the payment processor is active or not. If the processor is not active then you cannot create a payment method with that processor.

EnableLogging – optional
EnableLogging tells the system to log more detailed error / response message to the trace file in Sitefinity. You can locate this file at App_Data/Sitefinity/Logs/Trace.Log. Please note if you are integrating your own processor to the system, you are responsible for logging of the provider.

SectionName – optional
Name of the section that gets put into HTML in the backend of Payment Method Screen.

SectionCSSClass – optional (can accept multiple css classes separated by space)
CSS Class that gets applied to the section which can be used for DOM manipulations.

SettingsType – required

CLR name of the Settings object of the Payment Processor which gets persisted in the database. NOTE: all settings types should inherit from IPaymentSettings interface.

ViewProviderType – required
CLR name of the View that gets rendered while accepting payment method values. This has three parts to it
    1. ASCX file which contains the HTML that has be rendered
    2. C# file which inherits from FieldControl which controls Properties 
    3. Javascript file which is used to validate and serialize input to the system
An example of each of the above will be given to third party developers to make creating new payment processors easy.

ProviderType – required
CLR name of the concrete implementation of the payment processor. All Providers should inherit from IPaymentProcessorProvider interface and implement the methods.

Below is a screenshot on how your Settings area will look like if you have been following the sample code –

As always, I welcome your feedback and let me know if you questions about implementing the new Sitefinity Ecommerce Payment Provider Model.

progress-logo

The Progress Team

View all posts from The Progress Team on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.

Comments

Comments are disabled in preview mode.
Topics

Sitefinity Training and Certification Now Available.

Let our experts teach you how to use Sitefinity's best-in-class features to deliver compelling digital experiences.

Learn More
Latest Stories
in Your Inbox

Subscribe to get all the news, info and tutorials you need to build better business apps and sites

Loading animation