Hide menu Last updated: Oct 24 2016
Area: Episerver Commerce Applies to versions: 10 and higher
Other versions:

Creating a gift card payment provider

This topic explains how to create a payment provider for purchasing gift cards in Episerver Commerce. Functionality to deduct or add to the balance of the gift card is not included here - that must be added. You also create a new Business Foundation object and tie that to the existing Contact object. With this in place, you can create a gift card and assign that to a contact (customer). To use the gift card payment provider, you create classes and user controls. You must also complete a back-end customization and set it up.

Classes in this topic are available in the Mediachase.Commerce.Orders namespace.

Creating classes

Create a class that implements the IPaymentGateway interface.

  1. In Visual Studio, create a new project named GiftCardPaymentProvider.
  2. Delete the app.data folder, the web.config, and the Default.aspx files since they are not required.
  3. From the root of the site, create the folder structure: this adheres to Commerce Manager.
  4. Create a new class called GiftGateway.cs, which does the following:
    1. Returns the configuration data associated with a gateway.
    2. Sets the configuration gateway data. This data typically includes information like gateway URL, account info, and so on.
  5. To the class, add: using Mediachase.Commerce.Orders; Resides in Mediachase.Commerce.Orders.IPaymentGateway.
  6. Add a reference to the Mediachase.Commerce.dll assembly.
  7. Implement the interface IPaymentGateway.

    Example: implementing the payment gateway interface

    public class GiftGateway : IPaymentGateway
        IDictionary<string, string> _configData;
    public bool ProcessPayment(Payment payment, ref string message) { OtherPayment p = (OtherPayment)payment; if (!String.IsNullOrEmpty(p.ValidationCode)) { GiftManager.DeactivateGiftCard(Settings["GiftCardMetaClass"], PrimaryKeyId.Parse(p.ValidationCode)); p.Status = "Processed"; } return true; }
    /// <summary> /// Returns the configuration data associated with a gateway. /// Sets the configuration gateway data. This data typically includes /// information like gateway URL, account info and so on. /// </summary> /// <value>The settings.</value> /// <returns></returns> public virtual IDictionary<string, string> Settings { get { return _configData; } set { _configData = value; } } }

    Note : You can ignore error messages that occur at this step.

  8. Create a new class called GiftManager.cs (public static class GiftManager). See the following code comments.

Example: creating the GiftManager

public static class GiftManager
    public const string ContactIdFieldName = "ContactId";
    public const string AmountFieldName = "Amount";
    public const string BalanceFieldName = "Balance";
    public const string ContactFieldName = "Contact";
    public const string IsActiveFieldName = "IsActive";
public const string RedemptionCodeFieldName = "RedemptionCode"; public const string TitleFieldName = "Title";
public static EntityObject[] GetClientGiftCards(string giftCardMetaClass, PrimaryKeyId contactId) { return BusinessManager.List(giftCardMetaClass, new FilterElement[] { FilterElement.EqualElement(ContactIdFieldName, contactId), FilterElement.EqualElement(IsActiveFieldName, true) }); }
public static void DeactivateGiftCard(string giftCardMetaClass, PrimaryKeyId giftCardId) { // Load Gift Card EntityObject giftCard = BusinessManager.Load(giftCardMetaClass, giftCardId); // Update field giftCard[IsActiveFieldName] = false; // Save Changes BusinessManager.Update(giftCard); } }
9. Build the project.


Creating user controls

Create the user controls needed for the gift card payment provider.


Create a user control called ConfigurePayment.ascx. This user control needs to inherit from System.Web.UI.UserControl, IGatewayControl. See the code comments in the examples.

Example: creating the ConfigurePayment user control (part 1)

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="ConfigurePayment.ascx.cs"
	Inherits="GiftCardPaymentProvider.ConfigurePayment" %>
	<div id="DataForm">
	<table cellpadding="0" cellspacing="2">
		<td class="FormLabelCell" colspan="2"><b>Configure Gift Card</b></td>
	<br />
	<table class="DataForm">
		<td class="FormLabelCell"><asp:Literal ID="Literal4" runat="server" Text="MetaClass name" />:</td>
		<td class="FormFieldCell"><asp:TextBox Runat="server" ID="MetaClassName"
			<asp:RequiredFieldValidator ControlToValidate="MetaClassName" Display="dynamic"
			Font-Name="verdana" Font-Size="9pt" ErrorMessage="'MetaClass name' must not be left blank."
			runat="server" id="RequiredFieldValidator2"></asp:RequiredFieldValidator>

Example: creating the ConfigurePayment user control (part 2)

public partial class ConfigurePayment : System.Web.UI.UserControl, IGatewayControl
    string _validationGroup = string.Empty;
    private PaymentMethodDto _paymentMethodDto = null;
    private const string _metaClassParameterName = "GiftCardMetaClass";
/// <summary> /// Handles the Load event of the Page control. /// </summary> /// <param name="sender">The source of the event.</param> /// <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param> protected void Page_Load(object sender, System.EventArgs e) { BindData(); }
/// <summary> /// Binds a data source to the invoked server control and all its child controls. /// </summary> public override void DataBind() { BindData(); base.DataBind(); }
/// <summary> /// Binds the data. /// </summary> public void BindData() { // fill in the form fields if (_paymentMethodDto != null && _paymentMethodDto.PaymentMethodParameter != null) { var param = GetParameterByName(_metaClassParameterName); if (param != null)
{ MetaClassName.Text = param.Value;
} } else
this.Visible = false;
} }
/// <summary> /// Saves the object changes. /// </summary> /// <param name="dto">The dto.</param> public void SaveChanges(object dto) { if (this.Visible) { _paymentMethodDto = dto as PaymentMethodDto; if (_paymentMethodDto != null && _paymentMethodDto.PaymentMethodParameter != null) { var paymentMethodId = Guid.Empty; if (_paymentMethodDto.PaymentMethod.Count > 0)
{ paymentMethodId = _paymentMethodDto.PaymentMethod[0].PaymentMethodId;
var param = GetParameterByName(_metaClassParameterName); if (param != null)
{ param.Value = MetaClassName.Text;
} else
{ CreateParameter(_paymentMethodDto, _metaClassParameterName, MetaClassName.Text, paymentMethodId);
} } } }
/// <summary> /// Gets the name of the parameter by. /// </summary> /// <param name="name">The name.</param> private PaymentMethodDto.PaymentMethodParameterRow GetParameterByName(string name) { var rows = (PaymentMethodDto.PaymentMethodParameterRow[])_paymentMethodDto.PaymentMethodParameter.Select(String.Format("Parameter = '{0}'", name)); if (rows != null && rows.Length > 0)
{ return rows[0];
} else
return null;
} }
/// <summary> /// Creates the parameter. /// </summary> /// <param name="dto">The dto.</param> /// <param name="name">The name.</param> /// <param name="value">The value.</param> /// <param name="paymentMethodId">The payment method id.</param> private void CreateParameter(PaymentMethodDto dto, string name, string value, Guid paymentMethodId) { var newRow = dto.PaymentMethodParameter.NewPaymentMethodParameterRow(); newRow.PaymentMethodId = paymentMethodId; newRow.Parameter = name; newRow.Value = value; // add the row to the dtoif (newRow.RowState == DataRowState.Detached) dto.PaymentMethodParameter.Rows.Add(newRow); }
/// <summary> /// Loads the object. /// </summary> /// <param name="dto">The dto.</param> public void LoadObject(object dto) { _paymentMethodDto = dto as PaymentMethodDto; }
/// <summary> /// Gets or sets the validation group. /// </summary> public string ValidationGroup { get { return _validationGroup; } set { _validationGroup = value; } } }


Deploy the GiftCardPaymentProvider assembly to the Commerce Manager and the Episerver Commerce sites. We also deploy the user controls into specific folders.

  1. Deploy files by copying the GiftCardPaymentProvider to the sample project website and Commerce Manager website.
  2. The configured system keyword of the payment provide is GiftCard. Therefore, folders with that name must be created in the Payment\Plugins folder of respectively Commerce Manage and the front end website.
  3. Create a folder in the Commerce Manager payment plugin folder with the name GiftCard. Put the ConfigurePayment.ascx there. The path resolves to the following: [~CommerceManagerSite]\Apps\Order\Payments\Plugins\GiftCard\
  4. Create a folder in sample site payment plugin folder with the name GiftCard. Put the PaymentMethod.ascx there. That path resolves to the following: [~Commerce SampleSite]\Templates\Sample\Units\CartCheckout\GiftCard\.

Adding the gift card in Commerce Manager

Adding a business object

  1. Go to Commerce Manager > Administration > Business Foundation > Create New > New Business Object.
  2. Name the new object Gift Card, and notice the Plural Name. Leave the field info section entries to their defaults.

    Gift card payment provider configuration

  3. Add a new field to the Gift Card object called Amount. Note that the data type is Currency.

    Gift card payment provider configuration

  4. Add a new field to the Gift Card object called Balance, data type Currency.

    Gift card payment provider configuration

  5. Add a new field to the Gift Card object called IsActive, data type Boolean.

    Gift card payment provider configuration

  6. Add a new field to the Gift Card object called RedemptionCode.

    Gift card payment provider configuration

  7. Your Gift Card object should look like this.

    Gift card payment provider configuration

Making the gift card available

To make the gift card available to customers and to create easy management from the back-end, use the Business Foundation (BF) Relationship feature. To track and record relevant data, business objects must be related to other objects, whether they are 1-to-many, many-to-1, or many-to-many.

Note: The Related Object has the Primary Object appear under the opposite relationship (N:1) on its configuration form.

  1. From the main BF menu, select the Contact object, click the tab for 1:N Relations, then click the New Relation link in the right area of the screen.
  2. Fill in the information.

    Gift card payment provider configuration

  3. Click the dropdown Related Object, select Gift Card. Also, set Display Region to Information.
  4. Save your settings.
  5. Click Back To List and select the Gift Card object. The N:1 tab should look like this.

    Gift card payment provider configuration

Creating a payment method

Create a new payment method by using the Gift Card object.

  1. In Commerce Manager/Administration, navigate to the folder for the language of choice, such as English (United States).

    Gift card payment provider configuration

  2. Click New and enter information as follows. (Remember to switch to the Markets tab, then select markets for which this payment should be available).

  3. When done, click OK.
  4. Open the new Payment Method again, go to the Parameters tab, and enter GiftCard.

  5. Click OK.
  6. Go to the customer management section and select Contacts,
  7. Open up the contact admin and give admin an instance of the newly created Gift Card. The Gift Card is found under the Information section. (You chose that during the setup of the relation between Contact and Gift Card objects.)
  8. Click Add Items then New. Enter values as shown below

    Gift card payment provider configuration

Verifying the result

  1. Browse to the Episerver Commerce site and log in as an admin.
  2. Purchase an item.
  3. When you reach the Checkout wizard Payment Page, select Gift Card payment. Also, select the child instance radio button.