Overview
Hotcakes has several payment gateways ready and waiting for you to simply configure (in many cases with just your mouse). Once you do, you can begin accepting payments using that gateway immediately. That’s great, but what if you have a gateway that you need to support that is not in Hotcakes already? What if you need to change the way an existing payment gateway works? For example, you might need to support Authorize.Net Emulation. This sample project will help you support that gateway in no time at all.
Requirements
The following concepts and knowledge are required to complete the goals of this article:
- Familiarity with Visual Studio 2012 or newer
- Familiarity with the C# programming language
- General understanding of frameworks
- Have a development site ready with Hotcakes Commerce installed
- API documentation from your preferred payment gateway vendor
Getting Started
You are about to use a Visual Studio project to create the new gateway that you want to use in your Hotcakes Commerce store. A sample project can be downloaded on the right. The remaining documentation will walk you through how to effectively leverage this project.
Make sure you have a development website ready to accept API calls from your project. This would consist of the DNN CMS and Hotcakes Commerce. Also, if you do not already have products in your store, you should consider adding some or adding the sample products. This could even be a restored back-up of your production website.
Example Payment Gateway Project
If you haven’t done so already, make sure your site is up and running and ready for you to develop on it. We are about to have you set up your project. Once you understand how this works, feel free to set up your project and solution in any way that works for you. Also, please do not do this development work on your production website.
Open the download from above using your favorite zip utility. Grab all of the files from the zip archive and unzip them into the root of your development site.
If you receive any prompts from Windows, it’s likely that you already have a set of Hotcakes project files added to your development site. Go ahead and overwrite the files. This should result in the MyCreditCardGateway, References, and MyCreditCardGateway.sln folders and files in your DNN folder like shown below.
Next, open the solution that is now in the root of your website. Double-clicking on it will do the trick. This will open Visual Studio and show your project open. Your Solution Explorer view should look similar to the image below.
If you expand the folders, you’ll notice that you have four (4) files that you will need to edit in order to fully create your new payment gateway. Each file and the changes it requires are further described below.
| File Name | Description |
| Edit.ascx | This contains the HTML that will be displayed when you choose to “Edit” your payment gateway. Add your setting fields to this file as necessary. |
| Edit.ascx.cs | This is a standard code-behind file for your Edit HTML. It allows you to map settings that are already saved to your HTML elements on page load, and to save any changed values to the Hotcakes API. |
| MyTestGateway.cs | This is a class file that will contain all of the API communications between your project and the payment gateway you are integrating with. |
| MyTestGatewaySettings.cs | This is a class file that allows you to manage settings for your gateway in an object-oriented way, and without needing to create and use your own data source object. |
The changes you need to make to each file are very minimal in most cases. These changes are described more in each section below.
Edit.ascx
When you first open this file, it will look something like the image below. Most payment gateways require a username and password, but you can either edit these existing fields or add your own.
As an example, your new gateway has an API endpoint. If you want to allow this URL to be configurable, you can add a field for it, as shown below.
Note how the HTML markup was basically copied and pasted from one of the other settings above it. This is because Hotcakes Commerce is using a form pattern that allows you to add input fields while maintaining a consistent user experience for the people that will be managing the store.
Continue adding settings as desired until you have all of the settings added that you want to have configured for your API. These settings can be an input fields like you normally would add in ASP.Net development.
Once you have added all of the settings that you need, you are done with this file. Save it and move on to the next file.
MyTestGatewaySettings.cs
This class file should have a public property created for every field that you wish for the store admin to edit. In the default example, you can see that it has a property for each setting, and the name of the setting matches the property. This is not required, but it makes it easier to troubleshoot settings if it becomes necessary. Just be sure that each property has unique settings and keep an eye out for typos in the name of each setting.
In following with our current example, you may want to add another setting that matches the Gateway URL setting that was created in your Edit.ascx.
It’s not a bad idea to set default values for each property to ensure that if the property is called before being populated by the API for any reason, it contains an acceptable value.
Once you have all of your settings added, save the file and close it. You’re done with it.
Edit.ascx.cs
You should have already updated your Edit.ascx and MyTestGatewaySettings.cs files before opening this file.
This class has two methods in it, LoadData and SaveData. These methods are required. You can add more methods and properties of your own as desired, but do not remove or change the signature of these methods. Doing so will cause your project to have errors and you will not be able to build your project.
LoadData
This method works very similar to a Page_Load in a standard ASP.Net application. It will be called before the page is shown to the store admin. This allows you to look for any saved settings and populate the Edit form fields as required. This would also be a good place to put default values when the user decides to remove values, or if they fail to change the values.
In the example below, we have added a line of code to add the saved GatewayUrl value to the txtGatewayUrl TextBox. Since this is a string value, if there isn’t already a saved setting value for GatewayUrl, it will simply add an empty string value to the TextBox.
SaveData
This method will be called after the store admin clicks the Update button to save the values that they have put into the form. Note how in the default example, each value is being trimmed from the ASP.Net controls, and assigned to the settings object in the MyTestGatewaySettings.cs file.
Like with the previous examples, you again will simply follow the sample code provided and save the values from the form into the newly created settings like shown below.
Once you have your new settings all wired up in both LoadData and SaveData, you can close this file. We are done with this one now.
MyTestGateway.cs
This should be the last file you edit when creating your new payment gateway. There are 10 members that are already in this class file that you need to be acquainted with. They are described in the table below.
| Member Name | Description |
| Name | This should be a unique name for your provider. It must match the name of the folder that you deploy your new payment provider to. Otherwise, you will receive the following error, “Error, editor is not based on HccCreditCardGatewayPart class” |
| Id | This read only property must return a unique ID known as a GUID. You should change this to use your own GUID. There are a number of GUID generators out there, including extensions for Visual Studio. |
| Settings | This property is simply a new instance of your MyTestGatewaySettings class. Nothing is needed to be changed in this property for now. |
| BaseSettings | This read only property should return the Settings property. Nothing is needed to be changed in this property for now. |
| MyTestGateway | This is the constructor for the class. It should instantiate a new instance of the MyTestGatewaySettings class and assign it to the local Settings property. Nothing is needed to be changed in this property for now. |
| Authorize, Charge, Capture, Refund, Void | These methods must contain the code necessary to contact the payment gateway you’re using to perform the task indicated by the method name. You are passed a transaction object that contains all of the information input by the customer. Be sure that you populate that transaction object with the results you get from your payment provider. You must also call the ProcessOperation method that you see. It should be the last line of code in the method. |
| ProcessOperation | This method will properly apply the results from the transaction method that was called just prior to this method being called. Your example allows you to specify if the transaction occurred successfully or not. Once you do, use the example to properly add messages to your store and to update the reference number. |
Deploying Your Code – Development Environment
If you are in your development environment, all you would need to do is:
- Ensure that you are building to the /Bin directory of your website
- Copy your Edit.ascx to the same path in your DNN site
Here is an example of the path that your Edit.ascx needs to be in, where <FolderName> is the same name as what you specified in the Name property of the MyTestGateway.cs class.
~/DesktopModules/Hotcakes/Core/Admin/Parts/CreditCardGateways/<FolderName>
Right now, this name is probably MyTestGateway, so the path would look like the next example. The folder will need to be created the first time.
~/DesktopModules/Hotcakes/Core/Admin/Parts/CreditCardGateways/MyTestGateway/
Once you copy the DLL and Edit.ascx files, choose the new gateway in your Store Admin > Settings > Payment Methods view. Click the Edit link.
Select the new payment provider you created in the appropriate drop down list as shown below.
If you choose to edit this provider, you will see your new settings like below.
Deploying Your Code – Production Environment
Once you are happy with the results of your payment gateway, build it in release mode and copy the DLL you have built to the /Bin directory of your production website. The name of the DLL will be whatever you have chosen to name it in your project properties.
You would also copy the Edit.ascx file into the same path in your production environment. If this is your first time deploying the payment provider, you’ll need to create the folder.
That’s it… We hope you think that this is as easy as we do!
Need More Help?
Do you need more assistance with this article? Please review your support options.