Example - Directly integrating a custom payment gateway |
|||||
Example - Directly integrating a custom payment gateway |
|
||
The process of directly integrating a custom payment gateway can be divided into three logical parts.
1. Defining the required classes
2. Registering the payment gateway in the system
3. Registering the payment gateway in shipping options
Besides, the Using the payment gateway during the checkout process section shows how your customers can use a custom payment gateway during the checkout process.
This section demonstrates how to write classes providing functionality for your custom payment gateway.
1. Open your web project in Visual Studio and add two new classes into the App_Code folder (or Old_App_Code folder if the project is installed as a web application). Name the classes CustomGatewayLoader.cs and CustomGateway.cs.
2. Edit the classes and change their code to the following:
[C#]
using System;
using CMS.GlobalHelper; using CMS.SettingsProvider; using CMS.Ecommerce;
/// <summary> /// CustomGatewayLoader e-commerce loader class. Partial class ensures correct registration. /// </summary> /// [CustomGatewayLoader] public partial class CMSModuleLoader { #region "Macro methods loader attribute"
/// <summary> /// Module registration /// </summary> private class CustomGatewayLoaderAttribute : CMSLoaderAttribute { /// <summary> /// Constructor /// </summary> public CustomGatewayLoaderAttribute() { // Require E-commerce module to load properly. RequiredModules = new string[] { ModuleEntry.ECOMMERCE }; }
/// <summary> /// Initializes the module. /// </summary> public override void Init() { // This line provides the ability to register the classes via web.config cms.extensibility section from App_Code. ClassHelper.OnGetCustomClass += GetCustomClass; }
/// <summary> /// Gets the custom class object based on the given class name. This handler is called when the assembly name is App_Code. /// </summary> private static void GetCustomClass(object sender, ClassEventArgs e) { if (e.Object == null) { // Provide your custom classes. switch (e.ClassName.ToLower()) { // Create a custom getaway object inheriting from CMSPaymentGatewayProvider. case "customgateway": e.Object = new CustomGateway(); break; } } } }
#endregion } |
[C#]
using System; using System.Collections.Generic; using System.Text; using System.Web; using System.Collections;
using CMS.EcommerceProvider; using CMS.GlobalHelper; using CMS.UIControls; using CMS.ExtendedControls;
/// <summary> /// Class representing the Custom Gateway processor. /// </summary> public class CustomGateway : CMSPaymentGatewayProvider { /// <summary> /// Returns a payment gateway form with custom controls. /// </summary> /// <returns></returns> public override CMSPaymentGatewayForm GetPaymentDataForm() { try { return (CMSPaymentGatewayForm)this.ShoppingCartControl.LoadControl("~/CustomGatewayForm.ascx"); } catch { return null; } }
/// <summary> /// Process payment. /// </summary> public override void ProcessPayment() { // Get payment gateway url. string url = this.GetPaymentGatewayUrl();
if (url != "") { // Initialize payment parameters. Hashtable parameters = InitializePaymentParameters();
// Add required payment data to the url. url = GetFullPaymentGatewayUrl(url, parameters);
// Redirect to payment gateway to finish payment. this.ShoppingCartControl.Page.Response.Redirect(url); } else { // Show error message - payment gateway url not found. this.ErrorMessage = "Unable to finish payment: Payment gateway url not found.";
// Update payment result. this.PaymentResult.PaymentDescription = this.ErrorMessage; this.PaymentResult.PaymentIsCompleted = false;
// Update order payment result in the database. this.UpdateOrderPaymentResult(); } }
/// <summary> /// Returns table with initialized payment parameters. /// </summary> /// <returns></returns> private Hashtable InitializePaymentParameters() { Hashtable parameters = new Hashtable();
parameters["orderid"] = this.ShoppingCartInfoObj.OrderId; parameters["price"] = this.ShoppingCartInfoObj.TotalPrice; parameters["currency"] = this.ShoppingCartInfoObj.Currency.CurrencyCode; parameters["cardnumber"] = Convert.ToString(this.ShoppingCartInfoObj.PaymentGatewayCustomData["CustomGatewayCardNumber"]);
return parameters; }
/// <summary> /// Returns payment gateway url with payment data in query string. /// </summary> /// <param name="url">Payment gateway url.</param> /// <param name="parameters">Initialized payment paremeters.</param> /// <returns></returns> private string GetFullPaymentGatewayUrl(string url, Hashtable parameters) { foreach (DictionaryEntry parameter in parameters) { // Add payment data to the url. url = URLHelper.AddParameterToUrl(url, Convert.ToString(parameter.Key), HttpUtility.UrlEncode(Convert.ToString(parameter.Value))); } return url; } } |
Once you have implemented the classes, you need to register your custom payment gateway as an object in Kentico CMS.
1. Navigate to CMS Desk -> E-commerce -> Configuration -> Payment methods and click New payment method.
2. Enter the following values into the payment method's properties:
•Display name: Custom gateway
•Code name: Leave the (automatic) option. The system will generate the code name as CustomGateway (based on the display name).
•Description: Enter payment gateway description (optional).
•Teaser image: Upload payment gateway teaser image (optional).
•Allow if no shipping is supplied: yes
•Enabled: yes
•Payment gateway URL: ~/Special-Pages/Temporary-Payment-Page.aspx
•Payment gateway assembly name: App_Code
•Payment gateway class name: customgateway
•Order status if payment succeeds: In progress
•Order status if payment fails: Payment failed
3. Click Save.
Your new payment gateway is now fully functional and ready for use in the system.
|
If you registered your custom payment gateway as a global payment method, you need to enable it for use on the current site. You can do this in CMS Desk -> E-commerce -> Configuration -> Store settings -> Global objects.
|
To enable the use of your custom payment gateway during the checkout process, the last step you need to take is to register it in selected shipping options.
1. Navigate to CMS Desk -> E-commerce -> Configuration -> Shipping options.
2. Edit () a shipping option where you want to add your custom payment gateway on the Payment methods tab.
3. Click Add payments and in the Select payment dialog that opens select Custom gateway. Click OK.
As you can see, your custom gateway is now listed among other payment methods available for the current shipping option.
4. (Optional) Repeat this procedure to register your custom gateway in other shipping options.
If your customers select during the checkout process a shipping option to which you added your custom payment gateway, they can use the gateway as any other payment method available.