CCBill WHMCS Billing Module

What is WHMCS?

WHMCS is a complete client management, billing, and support solution for online hosting businesses. Since 2005, they have been helping web hosting companies automate their operations, reduce costs, and deliver a better experience to their end-users. With a wide range of integrations, WHMCS can provide a unique centralized platform for managing your web hosting business. They handle everything from customer signup to provisioning and support.

Introduction

The goal of this document is to provide installation and configuration instructions for the CCBill WHMCS billing module. This document assumes that the reader has a working knowledge of WHMCS and has already signed up for WHMCS.

The CCBill WHMCS billing module is used for WHMCS for both one-time and recurring billing. This module is compatible with WHMCS 6.2.0.

Overview

The CCBill WHMCS billing module enables easy integration of your CCBill account within the WHMCS platform. Installation involves the following steps:

  1. Installing the CCBill payment module for WHMCS.
  2. Configuring your CCBill account for use with WHMCS.
  3. Configuring the CCBill Payment Gateway in the WHMCS admin panel.

Installation Procedure

The CCBill WHMCS module is installed by uploading the extracted (unzipped) plugin code downloaded from the CCBill website into the appropriate folders of your WHMCS installation, as outlined below:

WHMCS root directory structure.

*ccbillerror.tpl

Please note that ccbillerror.tpl needs to be copied to the folder of the WHMCS template in use. For example, if you are using template Six, copy ccbillerror.tpl to folder six.

Configuring Your CCBill Account

Before using the plugin, it is necessary to configure a few things in your CCBill account. The following CCBill settings must be correct for the payment module to work correctly.

Enable Dynamic Pricing

Please work with your CCBill support representative to activate Dynamic Pricing for your account. You can verify that Dynamic Pricing is active at Account Info > Manage the Sub Accounts > Feature Summary in the Admin Portal. Your Dynamic Pricing status appears at the bottom of the Billing Tools section.

Enabling Dynamic Pricing in the CCBill Admin.

Creating a Salt / Encryption Key

A "salt" is a string of random data used to make your encryption more secure. CCBill Merchant Support will generate your Salt/Encryption Key. Once set, it will be visible at Sub Account Admin > Advanced. It will appear in the Encryption Key field of the Upgrade Security Setup Information section.

Creating a Salt Key in CCBill's Admin.

Disabling User Management

Since this account will be used for Dynamic Pricing transactions (not managing user subscriptions), User Management must be disabled.

1. Sign in to the Admin Portal.

2. On the Account Info mega menu, click Sub Account Admin, then User Management on the left menu.

3. Select Turn off User Management in the top section.

4. Select Do Not Collect Usernames and Passwords in the Username Settings section.

Disabling User Management in CCBill's Admin.

Configuring CCBill Webhooks

For the plugin to work, you will need to set up CCBill Webhooks. To do so:

1. Log into the CCBill Admin.

2. Open the Account Info mega menu and navigate to Sub Account Admin.

3. Select Webhooks from the navigation pane on the left.

4. Under Webhook URL, enter the base URL for your WHMCS store, followed by:

modules/gateways/callback/ccbillmodule.php

For example, if your WHMCS store is located at www.teststore.com, the Approval URL would be:

www.teststore.com/modules/gateways/callback/ccbillmodule.php

5. If you entered a Webhook Key (optional) on the CCBill module configuration page, you must append that value to the Approval URL. For more details regarding the Webhook Key, please refer to CCBill Options in WHMCS.

modules/gateways/callback/ccbillmodule.php?whKey=''value''

For example, if your whKey value is 12345, the Approval URL would be:

http://www.teststore.com/modules/gateways/callback/ccbillmodule.php?whKey=12345

6. NewSaleSuccess, RenewalSuccess, NewSaleFailure, and Cancelation are REQUIRED Webhook notifications for the CCBill WHMCS plugin.

Create a New Payment Form

The payment form is the CCBill form that will be displayed to your clients. The payment form accepts customer payment information, processes the payment, and sends the client to a designated URL after the payment has been processed.

Below you will find additional instructions on how to create a FlexForm payment form. If you need a more in-depth user guide, please refer to our FlexForms Overview.

Creating a Payment Flow and FlexForm

To create a FlexForm for use with Ubersmith:

1. Ensure All is selected in the top Client Account drop-down menu. FlexForms are not specific to sub accounts and cannot be managed when a sub account is selected.

2. Navigate to the FlexForms Systems tab in the top menu bar and select FlexForms Payment Links. All existing forms will be displayed in a table.

Create an Approval URL

Once a consumer has made a successful payment through CCBill, they need to be redirected back to your WHMCS online store. To do so, we need to define a redirect URL upon approval.

1. Click the URLs Library button in the upper-right corner of the screen to create a new URL. The Saved URLs Editor dialog displays.

2. Use the fields under Add New to create a new URL with the following properties.

Saved URL menu in CCBill FlexForm menu.
  • URL Name. Enter a meaningful name for this URL (e.g. “WHMCS Payment Success”).
  • URL. Under URL, enter the URL of your WHMCS store.

3. Click Save to commit your changes. Your new URL displays under Existing List.

4. Promote to Live.

  • Click Promote under the Actions column. Your URL is now live.
  • Close the Saved URLs editor to return to the main FlexForms menu.

Create a New FlexForm

1. Click the Add New button in the upper left to create a new payment flow. You are now essentially editing the first tile of the Payment Flow. In this case, you will be creating a FlexForm payment form for your WHMCS clients.

Create a new FlexFrom in CCBill's Admin.

2. The New Form dialog is displayed:

The main FlexForm menu.
  • Payment Flow Name. At the top, enter a name for the new payment flow (this will be different than the form name, as a single form can be used in multiple flows).
  • Form Name. Under Form Name, enter a name for the form.
  • Pricing. You need not assign any Price Points to this form. Prices will be dynamically inserted.
  • Dynamic Pricing. Under Pricing, check the box to enable dynamic pricing. This is a requirement for the integration to work.
  • Layout. Select your desired layout and save the form.
  • Theme. Select a predetermined color theme.

3. Edit the Flow. Click the arrow button to the left of your new flow to view the details. Under the green Approve arrow, click the square to modify the action.

  • Approval URL. In the left menu, select A URL. Select a Saved URL, and select the Approval URL you created earlier. This should be the base URL of your WHMCS online store.

4. Promote to Live. Click the Promote to Live button to enable your new form to accept payments.

5. Take note of the FlexForms ID. You will need to provide the FlexForm ID on the CCBill Payment Gateway Module page in the WHMCS admin panel.

All of these settings and many other can be modified in the FlexForms Editor at every moment. Pop up the Editor by clicking the Forms Library button in the upper-right corner of the screen. There you can create new forms as well, by clicking the Create New Form button.

Configuration - WHMCS

In the top menu of your WHMCS admin panel, please select Setup > Payments > Payment Gateways. Select All Payment Gateways and find and click the CCBill Payment Gateway Module option.

To configure the module, select Manage Existing Gateways.

The CCBill payment module menu in WHMCS.

The next section will outline how to fill in the fields on the CCBill Payment Gateway Module page.

CCBill Options

On the CCBill Payment Gateway Module page, enter the following information.

Show on Order FormMake sure to check this option to enable CCBill Payment processing.
Client Acct #Enter your CCBill merchant account number.
Client Sub Acct #Enter your CCBill merchant sub-account number.
Flex IDEnter the FlexForm ID created during the CCBill account configuration.
SaltEnter your salt/encryption key obtained during CCBill configuration.
Webhook Key (Optional)This is an optional parameter. However, it is advised to define a Webhook Key for added security.

Click Save Changes at the bottom of the CCBill configuration section.

Confirmation

You are now ready to process payments via CCBill!

Products you create in WHMCS will now interact with the CCBill shopping cart and checkout process.

Please conduct a few test transactions (using test data provided by CCBill) to ensure proper operation before enabling live billing mode in your CCBill account.

Support Options and Additional Resources

WHMCS

CCBill