CartThrob Lite Version 2.3.3

Tags

NOTE ExpressionEngine 2.5.2 + is REQUIRED to run CartThrob2 (lite). Lesser versions may be able to run CartThrob 2.2, but they are not supported.

CartThrob2 (lite) is a simple payment processing system for ExpressionEngine that will fit any budget. CartThrob2 (lite) allows you to process payments using leading industry payment gateways including Authorize.net and Paypal. It is ideal for websites that do not need the overhead of a full cart. It works especially well for processing single payments for things like donations, deposits, or single items.

Features
Requirements
Installation
Upgrading
Settings
Tags

Features

Checkout Form
Support for many popular payment gateways
Email notifications
Auto-install & Simple configuration
Simple upgrade path to CartThrob2 Pro
Order data is stored in channel entries
Built in support ticket system

Essentially CartThrob2 (lite) is a single page checkout form. It includes 2 simple tags: checkout_form, and submitted_order_info. Those two tags are all you need to capture customer orders, and provide order feedback. All order data is stored as an order channel entry.

CartThrob2 (lite) easily integrates with existing sites, and is a breeze to upgrade to CartThrob2. All CartThrob2 (lite) template tags are compatible with CartThrob2 Pro.

CartThrob2 (lite) is primarily focused on taking payments and staying simple. If you need additional features like member creation during checkout, member data merging, shipping & tax calculations, or the ability to add products to a cart, CartThrob2 Pro is a better option.

Requirements

ExpressionEngine 2.5+
PHP 5.3+

Installation

Upload the /system/expressionengine/third_party/cartthrob_lite/ folder to /system/expressionengine/third_party/
Place the themes/third_party/cartthrob directory into your/themes/third_party directory.
Make sure Extensions are enabled on your system
Install the CartThrob Lite module and extension (through EE's add-ons/modules panel)

Upgrading

Upload the /system/expressionengine/third_party/cartthrob_lite/ folder to /system/expressionengine/third_party/ Overwriting existing files.
Go to EE settings » addons » and click "Run Module Updates"

Upgrading to CartThrob2 Pro

At present there is no discounted price for upgrading to CartThrob2, but if you find you've outgrown the simple checkout form, you can upgrade to CartThrob2 easily. All you have to do, is purchase CT2, and overwrite all CartThrob2 (Lite) files with the CartThrob2 files, and follow CartThrob2's upgrading instructions.

Create an Encryption Key

In the control panel, go to Admin > System Administration > Config File Editor. Scroll down to $config['encryption_key'] and enter astrong encryption key. For more information on CodeIgniter's encryption key: "Setting your Key". Use something like 1Password or https://www.grc.com/passwords.htm to generate a strong key.

We strongly suggest not using an $ signs in your encryption key. PHP will interpret this character incorrectly when used as your encryption key.

Add Your License Code

In the Global section, you will see the "License Number" section. Please take some time to add your license code to your installation when you first install.

Auto-install Templates

Access your ExpressionEngine backend, and go to the Addons > Modules > CartThrob page. The Installation tab provides an "Auto-Install Templates and Channels" option. If you would like default templates and sample channels/sections set up to handle orders, we strongly recommend using these default templates the first time you install CartThrob to get a glimpse of the whole system at work out of the box. Customize from there.

Once you've configured the basic settings and have installed the default templates, take a look at the rest of the configuration settings to get a good idea of what the system can do.

`checkout_form`

Because there are no cart features you must specify a price in the checkout form as an input (with allow_user_price parameter set) or as a parameter. Otherwise the transaction will not have a cost associated with it.

checkout_form outputs a checkout form, gathers values for payment processing and initiates processing & payments. A CartThrob2 Standard video tutorial on this tag is available.. The video may not apply 100%, but it should be close enough to give you a feel for how this tag works.

NOTE If you would like to capture custom information in your order channel, create an input for your checkout form that has the same short_name as one of your order channel fields. So, if you have an order channel field called: "special_instructions", just add an input to your checkout form with the same short name like so: <input type="text" value="Don't leave on step" name="special_instructions" />. The custom information will be added to the order channel.

Parameters
Variables
Conditionals
Form Fields
Examples

Parameters

In addition to the parameters listed here, you may also use any of the CartThrob's Global Form Parameters.

required
cart_empty_redirect
gateway
price
allow_user_price
shipping
allow_user_shipping
country_code
expiration_date

`required`

Any fields required by the selected payment gateway are automatically validated. Use this parameter to require additional fields. Provide a pipe delimited list of required fields. Special values are 'all' and 'not'

required="shipping_first_name|shipping_last_name"

`cart_empty_redirect`

If the user's cart is empty, redirect them to this location.

cart_empty_redirect="cart/index"

`gateway`

This parameter is optional, normally you will want to use your configured payment gateway settings for security purposes. You can override the default payment gateway set in the extension by passing in the short_name of your chosen payment gateway. In more recent versions of CartThrob, there are a few new settings which will restrict the customer to only your selected gateway, or allow you to encrypt the names of your gateways for more security. In general we suggest deleting all payment gateways that you will not be using.

You can also pass this value via POST if you would prefer. Use a hidden field or a select field on your checkout page (for example) to set the payment gateway that will be used by the process function.

This is an example of the code that would be used on the Checkout form if you plan to pass the gateway file during checkout.

<input type="hidden" name="gateway" value="authorize_net" />

The short_name for each gateway can be found on its configuration page.

gateway="authorize_net"

`allow_user_price`

Allow your user to set a "price" for the checkout form. This is useful if you want to take donations. Just add a price input to your form. <input type="text" name="price" />

allow_user_price="y"

`price`

Set the price for the checkout_form. Advanced usage only. This will override the calculated cost of items in the cart, BE CAREFUL.

price="100"

`shipping`

Set the shipping price for the checkout form. Advanced usage only. This will override the calculated cost of shipping in the cart, BE CAREFUL.

shipping="50"

`country_code`

Can be used to set a default location for the checkout.

country_code="USA"

`expiration_date`

If you are saving your orders as entries, you may use this parameter to set the expiration date of the entry for this order. This parameter takes a number of DAYS from today's date to set the expiration date. This sets ExpressionEngine's channel entry expiration date.

expiration_date="365"

Variables

In addition to the variables listed here, you may also use any of the Global Tag Variables.

gateway_fields

`gateway_fields`

This outputs all fields required for the primary payment gateway, or the one selected using the gateway parameter. To edit the list of states and countries that are used, see Locales Config.

Conditionals

no_results}

`{if no_results}`

If there is nothing in the customers cart, they will be shown the no_results content.

{if no_results}

    Please <a href="{path=member/login}">login</a> or <a href="{path=member/register}">register</a> to complete your purchase.

{/if}

`use_billing_info`

This will override any submitted shipping info (shipping_first_name, shipping_address, etc.) with the submitted billing info.

<input type="checkbox" value="1" name="use_billing_info" />

`price`

This will override any set pricing costs. This must be used in conjunction with the allow_user_price parameter or this will be ignored

<input type="text" value="11" name="price" />

`shipping`

This will override any set shipping costs. This must be used in conjunction with the allow_user_shipping parameter, or this will be ignored

<input type="hidden" value="10" name="shipping" />

Examples

Use the "gateway_fields" variable to automatically output all required and optional fields used by your selected payment gateway. As long as the payment processor has been set up on the backend, this is all that is required to process a payment based on the amount currently in the cart. In the following example, we'll assume that the payment gateway settings have been configured.

{exp:cartthrob:checkout_form  
    id="myform" 
    name="myform" 
    class="myform" 
    return="cart/order_info" 
    onsubmit="your_custom_javascript()"
    }

    {gateway_fields}

{!-- You can also take a coupon code in addition to the standard fields at checkout 
    <input type="text" name="coupon_code" >--}

    <input type="submit" value="Checkout" />

{/exp:cartthrob:checkout_form}

OR, add your own inputs. NOTE: The required values vary by payment gateway, and are listed on each gateway settings page.

{exp:cartthrob:checkout_form  
    id="myform" 
    name="myform" 
    class="myform" 
    return="cart/order_info" 
    onsubmit="your_custom_javascript()"
    }
    <input type="text" name="first_name" value="" />
    <input type="text" name="last_name" value="" />
    <input type="text" name="address" value="" />
    <input type="text" name="city" value="" />
    <input type="text" name="state" value="" />
    <input type="text" name="zip" value="" />

    <input type="text" name="phone" value="" />
    <input type="text" name="description" value="" />
    <input type="text" name="email_address" value="" />

    <input type="text" name="shipping_first_name" value="" />
    <input type="text" name="shipping_last_name" value="" />
    <input type="text" name="shipping_address" value="" />
    <input type="text" name="shipping_city" value="" />
    <input type="text" name="shipping_state" value="" />
    <input type="text" name="shipping_zip" value="" />

    <input type="text" name="credit_card_number" value="" />
    <input type="text" name="expiration_month" value="" />
    <input type="text" name="expiration_year" value="" />

    <input type="submit" value="Submit" />
{/exp:cartthrob:checkout_form}

`submitted_order_info`

Returns transaction information about an order just placed. You should use this on any page specified as the return url for your checkout_form to show the customer success or failure of the order, as well as any other information saved to the order entry. This tag will natively parse ExpressionEngine channel entries variables, so it essentially acts as if it's a channel entry tag, preset with the entry id of your customers most recent completed or in process order entry.

NOTE: This tag requires that you use an Orders channel. If you do not use an order channel, only the following variables will be parsed by this tag: order_id, cart_total, transaction_id, error_message.

Variables

error_message
transaction_id
cart_total
order_id

`error_message`

Error message returned by the selected payment gateway. Typically, if any error message is returned, then the order has not completed.

This accursed transaction failed!

`transaction_id`

The transaction id returned by the selected payment gateway

123424455155

`cart_total`

The total amount of the purchase that was just made

$129.95

`order_id`

The entry ID of the order stored in the "orders" channel

Conditionals

if authorized
if declined
if failed

`{if authorized}`

If the transaction completed successfully.

{if authorized}Yay!!!{/if}

`{if declined}`

If the transaction was declined by the payment gateway.

{if declined}Boo!!!{/if}

`{if failed}`

If the processing failed.

{if failed}Fail{/if}

Examples

{exp:cartthrob:submitted_order_info}
    {if authorized}
        Your payment is a success!
        Transaction ID: {transaction_id}
        Your total: {cart_total}
        Your order ID: {order_id}
    {if:elseif declined}
        Your credit card was declined: {error_message}
    {if:elseif failed}
        Your payment failed: {error_message}
    {/if}
{/exp:cartthrob:submitted_order_info}

CartThrob Lite Version 2.3.3

Features

Requirements

Installation

Upgrading

Upgrading to CartThrob2 Pro

Create an Encryption Key

Add Your License Code

Auto-install Templates

Tags

checkout_form

Table of Contents

Parameters

required

cart_empty_redirect

gateway

allow_user_price

price

shipping

country_code

expiration_date

Variables

gateway_fields

Conditionals

{if no_results}

Form Fields

use_billing_info

price

shipping

Examples

submitted_order_info

Variables

error_message

transaction_id

cart_total

order_id

Conditionals

{if authorized}

{if declined}

{if failed}

Examples

`checkout_form`

`required`

`cart_empty_redirect`

`gateway`

`allow_user_price`

`price`

`shipping`

`country_code`

`expiration_date`

`gateway_fields`

`{if no_results}`

`use_billing_info`

`price`

`shipping`

`submitted_order_info`

`error_message`

`transaction_id`

`cart_total`

`order_id`

`{if authorized}`

`{if declined}`

`{if failed}`