Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Voucher Key Features (Introduced in v2.7)

  • Two types of vouchers; New Service & Renewal
  • Multiple billing cycles
  • Each voucher is map to a specific product in WHMCS
  • Can be used without Gift Card mode
Installation

Configuration

Enabling Voucher Mode

To enable Voucher Mode, go into your WHMCS Addon Modules → Gift Card Admin Module → Configure → Voucher Status

Template

Templates Used

New additional templates use for Voucher Mode are the following

Template file nameFunction

gcVoucherIndex_horizontal.tpl

The horizontal voucher listing template

gcVoucherIndex.tpl

The vertical voucher listing template

gcVoucherIndexOrder.tpl

The checkout page for voucher purchases

gcVoucherRedeem

The redemption page for vouchers

gcRedeem.tpl

The common page for checking a gift card/voucher code

gcVCManage.tpl

Language Uploads

The module includes English as the base language. If you wish to translate it to your enabled language in WHMCS. Make a copy of the english.php in /modules/addons/giftcard/lang/ to your associated language. For example, french.php. The filename must match to the ones in the WHMCS/lang/french.php

Configuration

Activation

Log into your WHMCS admin and enable the module by going to Setup → Addon Modules → Gift Card Module Admin → Activate

Once activated, click on Configure and fill in the license key and make any settings adjustment.

Image Removed

WHMCS Product Setup

During the initial module activation, the wizard will create a new Product Group and Product (Product Placeholder) in your WHMCS install. Both of these are hidden by default and it does not need to be shown to your customers. 

There are few things you would want to adjust before continuing.

  1. Update the Product groups (Gift Card Group) to only allow certain type of payment. This important as you don't want to allow fraud to happen with gift cards

  2. Updating the Product,

  • You may want to change the Product Name as this will be listed in the invoice item.
  • Make sure the Welcome Email is matched with the Welcome email (Gift Card Available) the module had created during activation.
  • Tax, on or off? Some countries require Gift cards purchase to be taxed
  • Pricing, leaving it as 0.00. They will be adjusted accordingly during checkout
  • Module Settings → Module Name → Gift Card Provision Module

If you have updated the name of product placeholder, make sure you go back to the Module Configuration in Setup → Addon Modules → Configure and update to the new Product name accordingly to the Generic Product ID dropdown

Image Removed

Info
titleNote

The product and product is hidden because the module doesn't use the WHMCS system to checkout the order. However, it does use WHMCS's order system + API to manage the orders. Therefore, the Product Placeholder is needed for invoice iteming.

WHMCS Email Template Setup

The module will create the following two email templates into your WHMCS. Gift Card Available and Gift Card Sending Template

TemplateDescriptionUsable Template VariablesGift Card AvailableThis template is used for the Welcome Email for the Product (Gift Card) PlaceholderGift Card AssignedThis template is used when you Generate or Import Gift Card Codes in the Admin backend. This will send an notification email to your client that they had been assigned a new Card{$prefix}{$value}{$suffix}{$gc}Gift Card Sending TemplateThis template is used when your customer want to send out the gift card to their friends via email.{$prefix}{$value}{$suffix}{$gc}{$pm}{$expiry}{$expiration}Voucher Available (New in v2.7)This template is used for the Welcome Email for the Product (Voucher) Placeholder

Voucher Assigned

(New in v2.7)

This template is used when you Generate or Import Voucher Codes in the Admin backend. This will send an notification email to your client that they had been assigned a new Card{$vc}

Voucher Sending Template

(New in v2.7)

This template is used when your customer want to send out the voucher to their friends via email.

{$mapping}{$vc}{$pm}

{$expiry}{$expiration}

Gift Card Listing

In order for the module to work in the front end, you must have at least one Gift Card available for purchase.

To add a Card for sale, navigate to

Addons → Gift Card Module Admin → Card Management → Create New Listing

Image Removed

To understand what each option does, simply mouseover each option.

HTML codes: <p><br><b><strong><strike> can be used in the Card Description field

Voucher Mode (New in v2.7)

With Voucher Mode, it allows for a new style of card code (Voucher) to redeem a product in a one to one manner. There are two types of Vouchers available: New Service Voucher & Renewal Voucher. You can map each individual voucher for sale to a specific product in your WHMCS. You can set the length of the service the 

New Service Voucher

For vouchers set to New Service, the voucher redeemer can obtain a new service available in your WHMCS. The billing cycle for these type of voucher falls in line with the billing cycle available in WHMCS. 

With New Service Vouchers, you may require the redeemer to input a value (either a hostname or domain name) before a redemption is allowed. The input will be used in the domain field of the service. 

If you need additional value to be inputted by the user, please refer to the Advance Voucher Redemption Guide

Renewal Service Voucher

For vouchers set to Renewal, the voucher redeemer can extend their existing service within their account. The billing cycle for these type of vouchers are in line with the WHMCS billing cycle except for One Time. An additional cycle called Lifetime is available for renewal vouchers. When a user redeem a Lifetime voucher, their existing service will be updated to a One Time service and no further billing will occur for this service.

Cashier Mode (New in v2.5)

With Cashier Mode, you can allows for the customer to create their own Gift Card with their defined card value.

Image Removed

There are 4 options for Cashier Mode

OptionDescriptionCashier ModeEnable the mode for the particular Card Listing. Once enabled, the defined Card Face Value will be ignoredCashier Mode Minimum AmountThis define the minimum value the customer set the Card value asCashier Mode Maximum AmountThis define the maximum value the customer set the Card value asCashier Mode Discount PercentageThe percentage you want to give this particular card listing discount off the Face Value. For example, if you set 10 here. That means you will give 10% discount from the Card's purchase. If someone buy a $1000 card, they will get $100 off (10%)

Restriction Group (New in v2.5)

with the Restriction Group feature. You can now restrict which client in which WHMCS Client Group to be able to Purchase and/or Redeem Gift Card in a particular Gift Card Listing

To utilize this function.

  1. Create a new Restriction Group (Gift Card Addon  Card Management  Restriction Group) Figure 1

  2. Once created, go back to the Restriction Group and Edit

  3. Now you will be able to select which group is allow to buy/redeem for this Restriction Group

  4. Once you have the Restriction Group ready. Go back to Card Management then you will now see the new group you created in the Restriction Group option dropdown (Figure 2) for each Card Listing. You can now adjust accordingly

Figure 1Image Removed

Figure 2Image Removed

Info
titleNote

If a list is empty then that means it is allowed all. The list is activated when there is one or more group inside the list. If you want to allow all Client Groups except for one group (Eg. Group ABC), then you will need to add the rest of the group except Group ABC into the Allow to Buy/Redeem list.

Menus (Client Area)

With our seamless template setup, there is no template modification needed. To enable the Gift Card menu in your navigation bar go to the Configuration of the Module and use the following options

OptionDescription1) Display Gift Card in ServiceThis adds a new link in the Services sub-menu in the default navigation bar2) Display menu in navigation menuThis will add a new Gift Card sub-menu into the navigation bar3) Display My Gift CardThis will display a My Gift Card link in the Gift Card sub-menu4) Display Redemption LinkThis will display a Redemption link in the Gift Card sub-menu5) Display Buy Gift CardThis will display a Buy Gift Card in the Gift Card sub-menu6) Search Sub CardThis will display a Search Sub Card in the Gift Card sub-menu

If 2) is disabled, then 3-6 will not show up.

Frontend Workflow

The module work in this workflow

8) Client will only be able to Redeem the cards when it's Activated, not used and not expired
FlowURL
1) Client browse for gift cardindex.php?m=giftcard
2) Client add to cartindex.php?m=giftcard
3) Client select quantityindex.php?m=giftcard
4) Order added to WHMCS via API, client redirects to invoice pageindex.php?m=giftcard&action=checkout
5) Once order is paid, your WHMCS could automatically create/activate the cards (based on your Product Placeholder setting) or it will be in Pending Orders waiting on your action
6) Once the card is added to the system (Pending, Activated or Used), the client will be able to see it under their accountindex.php?m=giftcard&action=managegc or My Gift Cards under Services menu
7) Client will be able to manage the cards in either of the menusThe manage voucher page under a user within the client area

Creating a Voucher for Sale

To put a voucher up for sale, first you must create a New Voucher Mapping. 

Head to WHMCS → Addons → Gift Card Admin Module 

Then click on the Voucher Management tab and Create New Voucher Mapping

Image Added

On the next screen, you will be able to fill in the fields to create a new mapping

Voucher Mapping Options

Option NameExplanation
Voucher NameThe display name of the Voucher
Voucher MappingThe mapping which the voucher will redeem to
Voucher TypeSelect this voucher will be a new service or renewal
Billing Cycle (For New Service)The new service will set to this billing cycle
Extend Renewal (For Renewal)The selected existing service will have the next billing date extended to this period
Required Input for Redemption (For New Service)Whether the voucher require a user input to process the redemption. This value will be used in the domain field of the service.
Voucher ValueThe display value of the voucher. No bearing of the price
Voucher PriceThe selling price of the voucher
EnableEnable the selling of this voucher
Show on Voucher Listing IndexIf disabled, the voucher will not be visible on the listing but users will still be able to purchase
ValidationRequire user to perform validation before the voucher is provisioned
Validation ConditionThe condition which the module will require the user to perform a validation on new voucher orders
Allow Self UserAllow the purchaser of the voucher to redeem the voucher
Personalized Message (Email)Allow the purchaser of the voucher to send a personalized message when sending the voucher to a friend
Code LengthThe length of the voucher code
PrefixThe prefix to add in front of the voucher code during generation
Code StyleThe allowed characters in the voucher code
Code CombinationThe style of how the code is divided
ExpiryThe amount of time the voucher will go expire after activation 
Restriction GroupThe restriction group which is allow to purchase & redeem the voucher
Voucher DescriptionThe description of the voucher shown on the listing index

Click on Add to Listing to add this voucher to your voucher listing.

You will find current Voucher Mappings for your system under the Voucher Management tab as well. 

Image Added

Click on the bubble and it will expand the properties for the particular Voucher Mapping

Info
titleNote

You will not be able to delete a Voucher Mapping if there is an existing Voucher under it.

Operations

Buying

Your users can purchase a voucher by going to index.php?m=giftcard&action=indexvoucher of your WHMCS. You can simply enable the Menu options under the Module's config.

Image Added

Redemption

Once the user have an active voucher, they can goto index.php?m=giftcard&action=redeemgc of your WHMCS or click on the Gift Cards & Vouchers Redemption link in the menu above.

Advance Voucher Redemption Guide


Info
titleNote

We will not be providing support for any custom coding due to the complexity.


Part 1 - Template front end

If your WHMCS product require additional user input before it is provisioned, then you will need to add additional fields manually to the template.

To do this, open the  gcVoucherRedeem.tpl template. To add a new field, look at the codes under IF statement of

Code Block
languagexml
{if $data["type"] == 0}

{elseif $data["type"] ==1}

You may copy and paste and use the existing code such as 

Code Block
languagexml
<input type="hidden" id="requiredinputtype" value="1"/>
                                <div class="col-sm-12">
                                    <div class="form-group row">
                                        <label for="requiredinput-host" class="col-sm-2 col-form-label">{$ADDONLANG.gcPage_redeem_vc_requiredinput_1}</label>
                                        <div class="col-sm-10">
                                            <input type="text" class="form-control" id="requiredinput-host" placeholder="hostname">
                                        </div>
                                    </div>
                                </div>

Change the id so that you can distinguish it during PHP processing and Javascript validation

If you need this required input to show up with Hostname input, then put in the (["requiredinput"] == 1) condition. If show up with FQDN input, then put it in the (["requiredinput"] == 2) condition. For IP input, put it in the (["requiredinput"] == 3) condition.

If you need this required input to show up for all vouchers, then you need to create a new IF condition within the ({if $data["type"] == 0}) condition, and a ({else}) condition. 

For example,

Code Block
languagexml
                           {if $data["data"]["properties"]["requiredinput"] == 1}
                             <input type="hidden" id="requiredinputtype" value="1"/>
                                <div class="col-sm-12">
                                    <div class="form-group row">
                                        <label for="requiredinput-host" class="col-sm-2 col-form-label">{$ADDONLANG.gcPage_redeem_vc_requiredinput_1}</label>
                                        <div class="col-sm-10">
                                            <input type="text" class="form-control" id="requiredinput-host" placeholder="hostname">
                                        </div>
                                    </div>
                                </div>
                            {elseif $data["data"]["properties"]["requiredinput"] == 2}
                                <input type="hidden" id="requiredinputtype" value="2"/>
                                <div class="col-sm-12">
                                    <div class="form-group row">
                                        <label for="requiredinput-fqdn" class="col-sm-2 col-form-label">{$ADDONLANG.gcPage_redeem_vc_requiredinput_2}</label>
                                        <div class="col-sm-10">
                                            <input type="text" class="form-control" id="requiredinput-fqdn" placeholder="domain.com">
                                        </div>
                                    </div>
                                </div>
                            {elseif $data["data"]["properties"]["requiredinput"] == 3}
                                <input type="hidden" id="requiredinputtype" value="3"/>
                                <div class="col-sm-12">
                                    <div class="form-group row">
                                        <label for="requiredinput-ip" class="col-sm-2 col-form-label">{$ADDONLANG.gcPage_redeem_vc_requiredinput_3}</label>
                                        <div class="col-sm-10">
                                            <input type="text" class="form-control" id="requiredinput-ip" placeholder="1.2.3.4">
                                        </div>
                                    </div>
                                </div>
                             {else}
								**Your new codes
                            {/if}

If you need the required input to show up for a particular voucher mapping then you can perform a IF condition such as 


Code Block
languagexml
{if $data["data"]["id"] == X}

{/if}

Where X is the voucher's ID. 

Once you have added the fields, you may want to add additional Javascript validation.

Part 2 - PHP Backend

Warning
titleWarning!

Do not allow user input without running some sort of validation of user's input. 


You will want to run some validation in the backend before it is inserted into your database. To do this, open the following file

Code Block
languagetext
modules/servers/giftcardprovision/include/processhookVC.php

This file is not encoded. There for you can make any changes you need for New Service redemption that require additional user input.

The codes are in the redemptionProcessHook function. 

You can refer to the WHMCS AddOrder API guide for additional information.

That's it. You new codes should be running for your new inputs.

Running codes after successful Renewal Redemption

If you run any custom code after a user successfully redeemed a voucher, simply open the following file.

Code Block
languagetext
modules/servers/giftcardprovision/include/processhookVC.php

then you can insert your own code in the redemptionRenewalHook function.

The $vars variable contains the following

Code Block
languagephp
$vars = array("uid"=>$_SESSION['uid'],"vcdata"=>$vcdata);

$vcdata are the voucher's properties which you can locate it in the mod_giftcard_voucher table in the database

$serviceid is the service id of the user chose to extend the renewal to.


Table of Contents
maxLevel3
minLevel2
absoluteUrltrue