Introduction

The CCBill configuration is one of the more complex payment processing configurations within UltraCart, but this tutorial will attempt to walk you through it step by step.  We will cover:

• Migrating to Rotating Transaction Gateways
• Setting up the CCBill Rotating Transaction Gateway
• Configuring Items
• Understanding CCBill Recurring Orders
• Configuring Upsells
• Understanding Upsell Shipping
• Upsell Conversion Tracking and Order Flow
• Quick Cancels and Shipment Holds
• Checkout Forms
• Import Configuration by CCBill
• IP Address to Whitelist
• End-to-End Checklist

Migrating to Rotating Transaction Gateways

Typically a merchant will have a regular payment gateway (Authorize.Net, PayPal Web Payments Pro, etc.) and will use CCBill for their free trial/continuity orders only.  A single gateway is configured under:

The first thing that needs to happen is remove the configuration from the single transaction gateway page.

Now you should be on the Rotating Transaction Gateways page.

(See also: Rotating Transaction Gateway)

Migrate your existing gateway before configuring the new CCBill gateway.

After clicking the "migrate" button the existing gateway is moved from the regular transaction gateways tab to the rotating gateways tab.  Next, click on the new button and then define the rotating transaction gateway..  Give the RTG a code that identifies the gateway, "CCBILL" will work fine, and then set it to handle 0% of the traffic, leaving the existing gateway at 100% traffic.

Then scroll down to the gateway list and select the radio button for CCBill gateway:

The following table describes each of the configuration fields for CCBill.

The configured rotating gateway configuration will look like this:

DLE User Configuration

The DLE user configuration inside of CCBill takes place under:

When you are configuring the DLE user within CCBill make sure that you give the DLE user full permissions as well as configure the three public IP addresses for UltraCart.  Your DLE user should look like this:

CCBill DLE Data Types

It is important to make sure that the DLE data types are properly configured on the CCBill side. UltraCart utilizes the following DLE data types:

• NEW
• REBILL
• REFUND
• EXPIRE
• CHARGEBACK
• VOID
• CANCELLATION

The DLE data types are configured inside of CCBill under:

The CCBill DLE data types screen should like the screen shot below. The data types in red are the ones consumed by UltraCart. Make sure that the current setup says "Global Default".

Configuring Items

The item configuration for a CCBill continuity item has two additional sections that are different from a regular item.  First, on the auto order tab, there is an additional section for the CCBill specific information.

The form name will correspond to the particular offer that CCBill has setup.  Generally they will do a form for each of the products being sold through CCBill so that marketing content, terms, etc. are shown on the checkout.  There are also two additional fields for allowed types and subscription type id.  These values should be provided by CCBill support to match up with the form.  Some forms could have multiple allowed types for the purchase so it's important that the appropriate values are configured.  Please note that the values should be ten digits long.

Next is the configuration of the steps associated with the auto order item.

You still have to configure the steps, delays, etc. within UltraCart just like you would a regular auto order item, but select "CCBill" for the Managed By column. 

This tells UltraCart that CCBill is responsible for processing the payment.  Once CCBill processes the payment UltraCart will learn about the transaction via the DLE API and generate the corresponding order for the proper item.

The final step of item configuration is telling UltraCart that the CCBill rotating transaction gateway should be used and which CCBill sub-account is associated with this item.  On the "Other" tab of the item editor scroll down to Payment Specific Settings.

Notice the sub-account id is configured and the CCBILL rotating transaction gateway is selected.  This is what tells UltraCart that CCBill is being used when a particular item is purchased.  Only those items with the payment specific settings selected on them will be processed by CCBill.  All other transactions will take place through the primary gateway.

Understanding CCBill Recurring Orders

When CCBill is used for a recurring order the system that is managing the transaction is CCBill.  UltraCart polls the CCBill system hourly looking for new rebill transactions.  When those transactions occur, UltraCart looks up the original transaction within it's system and fires the next step of the auto order schedule.  So the sequence of events on an order looks like this:

1. Customer places original order through UltraCart/CCBill
2. CCBill waits the determined amount of time before the next payment (configured on CCBill's system)
3. CCBill charges the customer's card for the rebill.
4. UltraCart polls the CCBill system with the DLE API.
5. UltraCart generates the rebill order based upon the next step of the auto order schedule.

UltraCart's auto order history will reflect the linkage between the original and recurring orders.  If you need to cancel a recurring order or refund it then it has to take place inside of CCBill's system.  UltraCart will learn of these refunds, cancellations, etc. through the DLE API and update it's internal state on an hourly basis.

Configuring Upsells

CCBill can process upsells on their platform. CCBill handles them as a second charge against the customer's card and they will flow down as unique orders.  CCBill uses a sub-account for each item upsold.  To make this work with UltraCart we need to configure the relationship between CCBill sub-accounts and UltraCart items.  To do this go to:

On this page you will configure a one-to-one relationship between the sub-account and UltraCart item id.

Understanding Upsell Shipping

When CCBill generates an upsell it is a unique order in their system and in the UltraCart system.  This one-to-one match up between the system facilities proper flow of information such as tracking between the two systems.  It would however not be ideal for shipment of product.  Right now the UltraCart platform will automatically merge the two orders into what appears as a single order/packing slip for users of UltraShip.

Upsell Conversion Tracking and Order Flow

If you are going to utilize upsells in the CCBill system it is critical that you have them configure our receipt URL as an iframe on the first upsell.  The URL is listed at the bottom of this article in the important configuration section as "Three Second Receipt Redirect".  By iframing the UltraCart receipt URL it will provide an opportunity for all of your conversion and tracking code to fire off even if the customer does not accept the upsell.  You should test your entire checkout process with FireBug for FireFox and watch the upsell page load, the receipt URL load, and all your conversion tracking requests load.  Affiliate networks do not receive conversion notices or credit for upsell transactions. 

CCBill is going to generate a completely unique transaction ID in their system for each upsell that the customer selects.  UltraCart polls for these new transactions hourly with the CCBill DLE API.  When it sees a new transaction it will generate a separate new order within UltraCart based upon the upsell configuration performed above in this tutorial. 

Quick Cancels and Shipment Holds

When CCBill takes an order they authorize the customer's credit card.  CCBill then keeps that authorization open for 24 hours before settling the transaction.  They have found that a large number of cancellations take place within a few hours of a customer's order.  To reduce the amount of transaction fees that they incur they keep the authorization open until 24 hours goes by and then they capture it.  UltraCart has created a way to hold the order automatically for a certain amount of time before it flows down into UltraCart or transmits to your fulfillment house.  To configure this go to:

We recommend configuring this for 1440 minutes (one day).  If someone does a quick cancel on their order UltraCart will learn about it via the DLE API and reject the order before it has a chance to ship.

Checkout Forms

Most free trial sites will have an order form on their home page like the one shown below:

Below is sample HTML for this form. 

<form action="https://secure.ultracart.com/cgi-bin/UCEditor" method="POST" id="address_form">
	<input type="hidden" name="merchantId" value="PUT_YOUR_MERCHANT_ID_HERE">
	<input type="hidden" name="clearCart" value="true">
	<input type="hidden" name="ImmediateThirdPartyHandoff" value="true">
	<input type="hidden" name="shippingcountry" value="United States">
	<input type="hidden" name="add" value="PUT_YOUR_ITEMID_HERE"/>
	<div class="none">
	</div>
	<div class="errors">
		<h4>Please correct the following:</h4>
		<ol>
			<li>There are no errors.</li>
		</ol>
	</div>
	<div id="shiptitle">
		<img src="images/shiptitle.gif" width="211" height="39" alt=""/>
	</div>
	<dl>
		<dt>
		<label for="shippingfirstname">First Name</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippingfirstname" name="shippingfirstname"/>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="shippinglastname">Last Name</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippinglastname" name="shippinglastname"/>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="email">Email</label>
		</dt>
		<dd>
		<input type="text" class="text" id="email" name="email"/><br/>
		<span class="small">(We reserve your privacy 100%)</span>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="shippingdayphone">Phone</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippingdayphone" name="shippingdayphone"/><br/>
		<span class="small">(In case we need to call about delivery)</span>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="shippingaddress1">Address 1</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippingaddress1" name="shippingaddress1"/>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="shippingaddress2">Address 2</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippingaddress2" name="shippingaddress2"/>
		</dd>
	</dl>
	<dl>
		<dt>
		<label for="shippingcity">City</label>
		</dt>
		<dd>
		<input type="text" class="text" id="shippingcity" name="shippingcity"/>
		</dd>
	</dl>
	<dl>
		<dt>
		<label class="half" for="shippingstate">State</label>
		<label class="half" for="shippingpostalcode">Zip</label>
		</dt>
		<dd>
		<select id="shippingstate" class="half" name="shippingstate">
			<option selected="selected" value="">State</option>
			<option value="AA">AA</option>
			<option value="AE">AE</option>
			<option value="AP">AP</option>
			<option value="AL">Alabama</option>
			<option value="AK">Alaska</option>
			<option value="AZ">Arizona</option>
			<option value="AR">Arkansas</option>
			<option value="CA">California</option>
			<option value="CO">Colorado</option>
			<option value="CT">Connecticut</option>
			<option value="DE">Delaware</option>
			<option value="DC">Wash DC</option>
			<option value="FL">Florida</option>
			<option value="GA">Georgia</option>
			<option value="HI">Hawaii</option>
			<option value="ID">Idaho</option>
			<option value="IL">Illinois</option>
			<option value="IN">Indiana</option>
			<option value="IA">Iowa</option>
			<option value="KS">Kansas</option>
			<option value="KY">Kentucky</option>
			<option value="LA">Louisiana</option>
			<option value="ME">Maine</option>
			<option value="MD">Maryland</option>
			<option value="MA">Massachusetts</option>
			<option value="MI">Michican</option>
			<option value="MN">Minnesota</option>
			<option value="MS">Mississippi</option>
			<option value="MO">Missouri</option>
			<option value="MT">Montana</option>
			<option value="NE">Nebraska</option>
			<option value="NV">Nevada</option>
			<option value="NH">New Hampshire</option>
			<option value="NJ">New Jersey</option>
			<option value="NM">New Mexico</option>
			<option value="NY">New York</option>
			<option value="NC">North Carolina</option>
			<option value="ND">North Dakota</option>
			<option value="OH">Ohio</option>
			<option value="OK">Oklahoma</option>
			<option value="OR">Oregon</option>
			<option value="PA">Pennsylvania</option>
			<option value="RI">Rhode Island</option>
			<option value="SC">South Carolina</option>
			<option value="SD">South Dakota</option>
			<option value="TN">Tennessee</option>
			<option value="TX">Texas</option>
			<option value="UT">Utah</option>
			<option value="VT">Vermont</option>
			<option value="VA">Virginia</option>
			<option value="WA">Washington</option>
			<option value="WV">West Virginia</option>
			<option value="WI">Wisconsin</option>
			<option value="WY">Wyoming</option>
		</select>
		<input type="text" class="text half" id="shippingpostalcode" name="shippingpostalcode"/>
		</dd>
	</dl>
	<div style="display:none;">
	</div>
	<div class="submit_free" style="margin-bottom: 20px;">
		<button type="submit" onclick="exit=false">Order Now!</button>
	</div>
</form>

Import Configuration by CCBill

It is very important that CCBill configure three things on your account.

Approval Notification URL - https://secure.ultracart.com/cgi-bin/UCCCBillApproval

Denial Notification URL - https://secure.ultracart.com/cgi-bin/UCCCBillDenial

Three Second Receipt Redirect - https://secure.ultracart.com/checkout/receiptLoad.do

IP Address Whitelist

End-to-End Checklist

This checklist is provided to cover all the different gotchas that can arise when setting up a CCBill integration.

1. (Merchant to CCBill) Make sure you have requested fulfillment product support on your CCBill account.
2. (Merchant to CCBill) Make sure that you request the maximum API calls per hour be increased to at least 10.
3. (Merchant to CCBill) Make sure CCBill has configured the approval/denial/receipt URLs.
4. (Merchant to CCBill) If you are using upsells, make sure they properly iframed the receipt URL on the first upsell.
5. (Merchant in CCBill) Have you setup the DLE user properly including granting the IP addresses?
6. (Merchant in CCBill) Have you confirmed that all the required DLE data types are available and configured as global defaults?
7. (Merchant in UltraCart) Have you configured CCBill as a rotating transaction gateway within UltraCart?
8. (Merchant) Have you walked your entire checkout with FireBug and validated that all the proper pixels and the UltraCart receipt are firing?
9. (Merchant) Have you purchased your upsell and made sure that the order flows down into UltraCart via the DLE and links to the original order within 1 hour?
10. (Merchant in UltraCart) Have you verified that there are no errors in the CCBill Log?

At CCBill we have found that the most knowledgeable people to handle the CCBill side are Raymond Kelsey and Christopher Resuello.