+1-888-365-2779
Try Now
More in this section
Categories
Bloggers
Blogs RSS feed

Ecommerce Payment Provider Model

by Teresa Miller

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 sepearated 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.

14 comments

Leave a comment
  1. Jean Erasmus Dec 14, 2011
    The images of the screenshots is not legable. Can you please provide accompanying text?
  2. Jason Dec 19, 2011
    Hi Teresa,

    The link to download the Payment Provider Model Example is broken, could you say where can I download the example?

    Thanks,
    Jason 
  3. Casey Dec 29, 2011
    The download link is broken
  4. Richard Jan 03, 2012
    Please fix the link!
  5. Teresa Jan 03, 2012
    The link to the download is now fixed.  I apologize for the inconvenience.
  6. Richard Jan 04, 2012
    Thanks for updating the link.  I have downloaded and am following the guide.  I must say that this is a really good guide with great attention to detail.  To Telerik: Please make ALL guides like this!
  7. Richard Jan 04, 2012
    Thanks for updating the link.  I have downloaded and am following the guide.  I must say that this is a really good guide with great attention to detail.  To Telerik: Please make ALL guides like this!
  8. Richard Jan 05, 2012
    Hi, I've ready through and still need alot more information in order to integrate a custom payment process.  I understand SubmitTransaction() is called but how can I redirect the user to a 3D authentication section and then back to Sitefinity? It would be nice if you could cover an example of this!
  9. Volkan Mar 10, 2012
    Hi Teresa,

    Could you help me please. I followed the steps as written on blog. I have a problem like this.
    http://www.sitefinity.com/ClientsFiles/338652_PaymentProcessorProvidersError.JPG
    I wrote to form.
    http://www.sitefinity.com/devnet/forums/sitefinity-4-x/e-commerce/custom-payment-provider.aspx

    Thanks.
  10. Ankit May 14, 2012
    Hi Teresa,

    We have downloaded the Example of Payment Provider Model. and register it successfully at Sitefinity Backend. But we are facing a problem of duplicate desgin at Payment Method when we select our Custom Payment Processor. It shows its previous desgin as well as our custom Desgin.
    Please help us asap.

    Thanks

  11. OC Oct 14, 2012
    "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…"
    When is this ready? PayPal Express badly needed outside the US!!!
  12. Pelle Mar 08, 2013
    I wonder what "in the near future" means in terms of days, weeks...months...?
  13. Mark jacobson Feb 02, 2015
    I'm interested in the comment that "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…" Someone posted about this in Oct 2012 and there's been no response. What is the status?
  14. Ollie P Jan 18, 2016
    For anyone struggling implementing 3D secure, I found a solution which I describe here http://stackoverflow.com/questions/34742593/implementing-3d-secure-with-sitefinity-ecommerce

    Leave a comment