Custom Gift Card Gateway Example

Overview

We make it our mission to provide the most flexible e-commerce platform possible that allows you to fit the needs of nearly any e-commerce use case.  This is why we made sure that you have a way to implement your own or third-party gift card gateways.  This article will help you implement any custom gift card processor using the sample Visual Studio solution.  It's nearly the same as implementing a custom payment gateway for credit cards.

Requirements

The following is required to accomplish the goals of this article:

• How to use Visual Studio 2012 or newer
• Familiarity with C# and Razor
• General understanding of frameworks
• Have a site with Hotcakes Commerce 1.6.0 or newer installed and ready

Getting Started

Download Sample Gift Card Gateway Project

You are about to use a Visual Studio project to connect to your Hotcakes Commerce store.  The project can be downloaded on the right.  The documentation below will walk you through how to use this project.

Make sure you have a development website ready to develop against.  This would consist of the DNN CMS with Hotcakes Commerce installed and configured.  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 locally restored back-up of your production website.

Gift Card Gateway Sample Solution

If you haven’t done so already, make sure your site is up and running and ready for your project to call into 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 MyGiftCardGateway, References, and MyGiftCardGateway.sln folders and files in your site 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.

From this point, you are ready to begin writing the code necessary to create your new payment method.  This will primarily consist of the settings and API code required by your payment method of choice.  Your chosen payment method should have documentation and/or code samples to help with this.

SOLUTION FILES

You have a few files available for you to modify and they will all be necessary to work with for your new gift card gateway.  The table below will walk you through what each file is for.

File Name	Description
Edit.ascx, Edit.ascx.cs	This file will be injected into the Hotcakes store administration to allow you to display and save settings input by the merchant.  This is a common way to save API credentials, endpoints, and anything else that you need.  You should not change the name of this file.
MyTestGateway.cs	You can change the name of this class and file, as long as the GiftCardGateway class is implemented.  Initially, be sure to change the GUID in the Id property.  The Name can also be changed, provided that it matches the folder name of your new gift card gateway.  The rest of the methods should be implemented following the patterns and direction required by the API of the third-party gift card gateway.  In this example, be sure to at least change the implementation of the constructor, Charge, Refund, CreateNew, and BalanceInquiry methods.  The rest are not implemented.
MyTestGatewaySettings.cs	This class will strongly type the settings that your gift card gateway requires.  At a minimum, you will likely have authentication credentials here and you will likely have a setting property for each field in your Edit.ascx view.

STEPS TO BUILD/CODE

If you've made it this far, you're already well on your way.  Now, you just need to add and modify the code in the solution as discussed in the table above.  This may also include changing namespaces, DLL names, class/file names, and more.  When you're at a point to see what your changes look like, you need to follow the deploy steps below.

DEPLOYING YOUR CODE

There are different steps to deploying your code, depending on whether you're just developing or attempting to roll it out to a server (e.g., staging or production).

• Development
• Production

Deploying Your Code – Development Environment

If you are in your development environment, all you would need to do is:

1. Ensure that you are building to the /Bin directory of your website (debug mode)
2. Copy the Edit.ascx file to the same path in your DNN site:  ~/DesktopModules/Hotcakes/Admin/Parts/GiftCardGateways/YOURGATEWAYNAME/
3. Go to the store administration and change the gift card gateway to use the new custom order workflow in this project in the Settings > Gift Card Settings view

Once you copy the DLL and project files, you will be able to select the new payment method in your Store Admin > Settings > Gift Card Settings view.

You'll now see your custom gateway shown in the drop-down list.  If you select it, you can then edit the settings you added.

Here, you can see the settings from the custom project, as you defined them.  Don't forget to save them here and in the previous view.

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 same Edit.ascx file we moved during development into the same paths in your production environment.  If this is your first time deploying the payment method, you’ll need to create the folders as well.

That’s it… We hope you think that this is as easy as we do!