Overview
We can't implement every conceivable payment method that there is. That would be impossible. This is why we made sure that you have a way to add your own. This article will help you implement your own payment method, including a sample Visual Studio solution.
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
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.
Payment Method 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 MyPaymentMethod, References, and MyPaymentMethod.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 lot of files available for you to modify and they will all be necessary for most scenarios. The table below will walk you through what each file is for. There is also a ReadMe.txt file that contains a more brief version of this documentation.
| 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. |
| MyCustomWorkflowFactory.cs | In a custom payment method, you'll need to tell Hotcakes when and how to process the payment. This class uses the custom order workflow extension point to do just that. The task that you will want to change/edit is StartMyPaymentMethodCheckout(). This has a class in your sample solution. |
| MyPaymentMethod.cs | This class registers the payment method in Hotcakes so that it can be properly managed in the merchant and customer views. You will want to change the Id and MethodName properties. The method name needs to match the folder name of the payment method, which currently is "MyPaymentMethod." |
| MyPaymentMethodCheckoutController.cs | This class is executed just prior to the page load when the customer is sent back to your site, following payment. |
| MyPaymentMethodSettings.cs | If you have settings to save/retrieve using Edit.ascx, you will need to use this class. It manages settings for you. Add a property in the same pattern for each setting you need to save/retrieve. |
| StartMyPaymentMethodCheckout.cs | This is the custom order workflow task that is referenced by the MyCustomWorkflowFactory.cs class. It should contain the code required to process payments or a redirect to the third party payment processing page. Please remember to change the GUID and the Task Name before building. You should follow the instructions in the comments in the class file as well. |
| Controller.resx | This is a localization file and should contain the key/value pairs for text translations. The file naming convention for this payment provider works the same way as the underlying DNN CMS. The locale would be in the file name to support other languages, such as Controller.en-GB.resx for British English. |
| Index.cshtml.resx | This is the localization file for the Index.cshtml file below. |
| Index.cshtml | This is the Razor template file for the checkout landing page that your customer is sent to following a third party payment transaction. |
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, 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).
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 project files to the same path in your DNN site
- Go to the store administration and change the Active Order Workflow to use the new custom order workflow in this project in the Settings > Extensibility view
- Add a new key/value pair (MyPaymentMethodPayment.Text) to the _DisplayPaymentMethods.cshtml.resx file (this is for a partial view in the Checkout view of your custom viewset)
- Add a new key/value pair (MyPaymentMethod.Text) to the \DesktopModules\Hotcakes\Core\Admin\App_LocalResources\PaymentMethods.resx file (this is for the merchant views that display your new payment method)
The keys for the localization file changes need to also match the folder name. As an example, if your payment method folder name is "NextBigThing," then your localization keys will be NextBigThingPayment.Text and NextBigThing.Text, respectively.
Once you copy the DLL and project files, you will be able to select the new payment method in your Store Admin > Settings > Payment Methods 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 project files 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.
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.