Checkout Form (tag pair)

checkout_form outputs a checkout form, gathers values for payment processing and initiates processing & payments. A video tutorial on this tag is available..

Table of Contents

Parameters

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

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"
gateway_method

This parameter is optional and allows you to set the checkout method on gateways that support this functionality.

An example use case for this parameter is with the Mollie payment gateway that allows you to declare the specific checkout method ("creditcard", "ideal", "applepay", etc.) in the case where it is known at the time of checkout or in the case where the method should be hard coded.

The attribute will be added to whichever gateway is selected but will only be applied to gateway requests that support this functionality.

gateway_method="ideal"
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"
create_user

This parameter will allow you to create a member at checkout. If you have this parameter set to, add the following fields to create your member. See the example at the bottom of the page.

create_user="yes"
group_id

If you have create_user set, this is used to set the group ID of the new member. Any values lower than 5 are changed to 5 for security purposes. Leaving this value blank in conjunction with create_user, will make new users part of the "member" group (5).

group_id="6"
force_processing

This will force the checkout to not process the credit card and instead set the order to status processing upon form submission. If you are using subscriptions or are using force_vault, a vault token will be created for later use.

force_processing="yes"
force_vault

Normally, vaults will only be created when there is a subscription in the cart. Set this to yes to force the creation of a vault without having a subscription. Useful if you want to charge the purchase later on.

force_vault="yes"
vault_id

Specify an existing vault to use for payment by its ID.

vault_id="1"
member_id

If logged in as an admin, you can use this parameter to check out on behalf of the specified customer. If using an admin group other than the Super Admin user group, you'll need to select that admin group in the CartThrob Global settings tab's "Admin Checkout Groups".

member_id="1"
order_id

Complete an order that has "processing" status. If logged in as an admin, you can use this parameter to complete an in-processing order on behalf of the order's customer. The member_id parameter will be ignored if this is used.

custom_js

Disable the pre-composed JS for payment gateways, allowing for a fully custom experience for gateways like Stripe and Authorize.net. When enabled, checkout will fail if no custom implementation is added to the template or included JS files.

Variables

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

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.

captcha

If you have the "Require Captcha on Checkout Form for Guest Checkouts?" settings turned on, this will render the captcha image. Pair this with the if captcha conditional.

Conditionals

{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}

{if captcha}

If you have the "Require Captcha on Checkout Form for Guest Checkouts?" settings turned on and the user is a guest, this will evaluate to true. Pair this with the {captcha} variable.

{if captcha}
    <p>Please enter the word you see in the image below:</p>
    <p>{captcha}</p>
    <input type="text" name="captcha">
{/if}

Form Fields

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" />

meta:some_key

Stripe allows for metadata to be sent along with the payment submission. The metadata can then be viewed in the Stripe Dashboard or downloaded along with other payment information. Stripe permits up to 20 metadata fields with keys up to 20 characters long and values up to 500 characters long.

<input type="hidden" name="meta:ReferredBy" value="Wanda Sellalot">

<input type="text" name="meta:GiftFor" placeholder="Gift Recipient's Name">

<select name="meta:CheckoutExperience">
        <option value="5">Perfect!</option>
        <option value="4">Excellent</option>
        <option value="3">Good</option>
        <option value="2">Meh</option>
        <option value="1">Awful</option>
</select>

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}

Create a member at checkout Username and email_address are required. Screen name will use the username value if left blank. Password fields must match if set. If left blank, a random password will be generated.

{exp:cartthrob:checkout_form 
    create_user="yes"
    group_id="6"}
            <input type="text" class="required" name="username" value="" />
            <input type="text" class="required" name="email_address" value="" />
            <input type="text" name="screen_name" value="" />
            <input type="password" name="password"  value="" />
            <input type="password" name="password_confirm" value="" /> 

        {gateway_fields}

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

Buy Now

Top