Charge Upgrade Documentation

Tag Parameters

form_id

required
string

The ID to apply to the form.
Is used in the javascript setup.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"}

form_class

string

The class to apply to the form.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"}

return

url

The return url to come back to on success. This will get appended with a transaction hash, used with the {exp:charge:info} tag

{exp:charge:form
   return="/your/page"}

return_error

deprecated

url

The return url to come back to in the event of an error other than validation fail. Validation fails will return to the current url with the errors available as variables. Deprecated: As of Charge v3, all payments are handled over AJAX and no longer redirect during payment processing. Errors are handled inline on your payment form. See our migration guide for more information.

{exp:charge:form
   return="/your/page"
   return_error="/your/error/page"}

method

post or get

The method to set the form to, defaults to post

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    method="post"}

show_card_years_count

integer
defaults to '5'

Used to control how many upcoming years are returned in the {card_years}..{/card_years} tag pair

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    show_card_years_count="10"}

on_success

action_shortname

Short Name of Charge Action you want to trigger after a successful transaction. More info on Charge Actions here.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    on_success="your_action"}

on_success:variable_name

string

Used to supply extra information to Charge Actions to specify entry_id or url_title and any additional fields.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    on_success="update_entry_action"
    on_success:entry_id="3"
    on_success:url_title="my_entry"
    on_success:my_custom_field="awesome"
    on_success:member_fav_food="pizza"}

create_member

yes or no
defaults to 'no'

Create a member on success.

Only applies to non-logged in members.

The created account will have the details from the Member Fields, be added to the default site member group, and they will be immediately logged in.

This can be especially useful if you want to add a user to a subscription as the member account will be created first, then immediately added to any subscription as defined in the Charge Action settings.

Show Related Parameters

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    create_member="yes"}

Member Fields

You can give your users the choice whether they want to create an account, and if they want to supply a password as part of this form.

member_create

yes or no
defaults to 'yes'

Lets the user disable the member creation. Only used if create_member="yes" param has been passed on the form.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    create_member="yes"
    member_create="no"}

member_password
member_password_confirm

form only

Let the user set a password.

If member_password is passed, member_password_confirm will also be required, and must match.

If not passed, a random password will be generated for the user and you will need to provide a mechanism to allow a new user to reset their password.

<input name="member_password" type="text" />
<input name="member_password_confirm" type="text" />

member_username

Pass a username. If not provided, customer_email is used.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    create_member="yes"
    member_username="whatever"}

member_screen_name

fixed value

Set from the customer_name. Not editable.

Prior to version 1.15, member_screen_name is set with both the customer_name and the customer_email in the format of customer_name, customer_email.

plan_trial_days

param only
numeric
Defaults to '0'

Set the number of trial period days for a plan.

For safety, this value can only be set directly as a parameter on the form, not via any form inputs.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_trial_days="10"}

plan_balance

param only
recurring only
numeric
Defaults to '0'

Set the account balance for the customer. Negative values are credits, positive are amounts owed.

Usage Example: Take an extra one-time charge from a customer on the first payment of a recurring plan (like a setup fee) in addition to the recurring amount.

Pass negative values to have that value discounted from the customer's invoices. The balance credit will roll over if it's greater than the invoice amount.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_balance="10"}

plan_length

numeric

Used to define a set length for any subscriptions or recurring payments.

For example: '3' gives a plan length of 3 months (default interval) after which the subscription or recurring payment automatically ends.

The interval can be adjusted using the plan_length_interval param.

NOTE: If the plan_length_interval is set to 'month', the plan_length cannot exceed 12 months (Stripe limitation).

Learn more about how set length plans work

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_length="6"}

plan_length_interval

week, month, or year
Defaults to plan_interval
Defaults to 'month'

The interval to count for the plan_length.

If not set, will inherit from the plan_interval (if that's set), or default to 'month' otherwise.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_length="6"
    plan_length_interval="month"}

plan_set_name

param only
Added in 1.8.3
string

Give your plan a specific name instead of the automatically generated name.

Generated name is based on the plan parameters (ex: 75 USD Every [x] Month(s))

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_set_name="Gold Plan"}

required

pipe separated list

Add extra Charge Fields to the validation logic to make them required. Be sure to add the appropriate {error_field_name_message} tags to output your new validation messages.

Also works for any 'meta:...' fields but the field MUST be present on the form with curly braces (i.e. {meta:accept_terms}).

NOTE: You can only make 'meta:' fields and parameters/fields listed here 'required', custom fields that are not part of Charge or 'meta:' will not validate.

Learn more about required fields

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    required="Gold Plan"}

Customer Fields

customer_name

required
string

The name of the customer.

<input name="customer_name" type="text" />

customer_email

required
string

The email address of the customer.

This gets used to identify the customer inside Stripe.

<input name="customer_email" type="text" />

Plan Fields

plan_amount

required
numeric

The payment amount. Can be a fixed value in the {exp:charge:form} tag or as an editable input field.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_amount="65"}

<input name="plan_amount" value="65" type="text" />

plan_currency

string
Defaults to Stripe Currency

The currency to process the transaction in.

Defaults to the default currency in your Stripe account.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_currency="USD"}

plan_interval

recurring
week, month, or year
Defaults to 'month'

The interval of how often this plan recurs. Used in conjunction with plan_interval_count

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_interval="week"}

plan_interval_count

recurring
numeric

Optional, must be numeric if passed. If not passed, defaults to '0'. '0' is treats the payment as a one-off charge. Any other (valid) number is used as the count of the intervals, ie. 'every 3 months'.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_interval="week"
    plan_interval_count="6"}

plan_coupon

string

If passed a 'Coupon Code' (not the 'Coupon Name'), will be validated against the list of Charge Coupons and applied to the transaction or will return an error.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_coupon="10_off"}

Card Fields

card_number

required
form only

The all important card number. Gets tokenized by the Stripe.js before the server ever sees the value.

<input name="card_number" data-stripe="number" type="text" />

card_cvc

required
form only

The security code for the payment card. Tokenized by stripe.js

<input name="card_cvc" data-stripe="cvc" type="text" />

card_exp_month

required
form only
2 digits

The expiration month on the payment card. Tokenized by stripe.js

<input name="card_exp_month" data-stripe="exp_month" type="text" />

card_exp_year

required
form only
2 or 4 digits

The expiration year on the payment card. Tokenized by stripe.js

<input name="card_exp_year" data-stripe="exp_year" type="text" />

card_name

string

The name on the card.

<input name="card_name" data-stripe="name" type="text" />

card_address_line1

string

The address line 1 for the card holder.

<input name="card_address_line1" data-stripe="address_line1" type="text" />

card_address_line2

string

The address line 2 for the card holder.

<input name="card_address_line2" data-stripe="address_line2" type="text" />

card_address_city

string

The address city for the card holder.

<input name="card_address_city" data-stripe="address_city" type="text" />

card_address_state

string

The address state (of county) for the card holder.

<input name="card_address_state" data-stripe="address_state" type="text" />

card_address_zip

string

The address zip (or postcode) for the card holder.

<input name="card_address_zip" data-stripe="address_zip" type="text" />

card_address_country

2 character country code

The address country for the card holder.

<input name="card_address_country" data-stripe="address_country" type="text" />

card_save

Added in 1.10.0
yes or no
Defaults to 'yes'

Set the default card save behaviour. Pass 'no' to disable saving the payment card to the member's Stripe account.

Cards are NOT saved on your server.

I do not wish my payment card to be saved:
<input name="card_save" value="no" type="checkbox" />

have_payment_card

returns boolean

Denotes if the currently logged in member has a payment card that can be reused

{if have_payment_card}
    ...
{/if}

saved_card_field

All the card details for a saved card will be present as tags. i.e. {saved_card_type}, {saved_card_last4}, {saved_card_number_dotted}, etc

Your Card: {saved_card_type} {saved_card_number_dotted}

card_use_saved

yes or no
Defaults to 'no'

An input to allow the user to click a checkbox to use their saved card. Simply pass a value of 'yes' to use their saved card.

I wish to use my saved payment card:
<input name="card_use_saved" value="yes" type="checkbox" />

Meta Fields

meta:your_custom_field

string

The value of the {meta:your_custom_field} input passed. ie. Pass a field named 'meta:language', and the variable {meta:language} will be populated.

For error validation, you MUST have the {meta:your_custom_field} present on the page (with curly braces). An input of name="meta:your_custom_field" is not sufficient.

<input name="meta:your_custom_field" value="{meta:your_custom_field}" type="text" />
{if error_meta:your_custom_field}
    {error_meta:your_custom_field_message}
{/if}

Tag Variables

card_years

Defaults to 5 years

List X years to populate the credit card expiration year dropdown.

Years can be altered using the show_card_years_count parameter.

Within the {card_years} loop there are some additional variables to use:

Show Related Tags

{card_years}
    ...
{/card_years}

Card Years Tags

The following tags can be used inside the {card_years} loop to display either 4-digit or 2-digit versions of the years.

You can adjust how many years display by adding/changing the show_card_years_count parameter.

year_long

The year in 4-digit format. Ex: '2016'

<select name="card_exp_year">
{card_years}
    <option value="{year_long}">{year_long}</option>
{/card_years}
</select>

year_short

The year in 2-digit format. Ex: '16'

<select name="card_exp_year">
{card_years}
    <option value="{year_short}">{year_short}</option>
{/card_years}
</select>

card_months

List all the months of the year with tags for the numeric month, the short form of the month name, and the long form of the month name.

Also has a tag for current_month that returns a boolean if the current month in the loop matches the month we're in.

Show Related Tags

{card_months}
    ...
{/card_months}

Card Months Tags

The following tags can be used inside the {card_months} loop to display either the numerical month or the short or long form of the month name.

You can also test the months in the loop agains the {current_month} tag.

month_digit

The digit for the current month, ie. for January return '01'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_long}</option>
{/card_months}
</select>

month_long

Returns the full word for the current month, ie. 'January'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_long}</option>
{/card_months}
</select>

month_short

Returns the short code for the current month, ie. 'Jan'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_short}</option>
{/card_months}
</select>

current_month

A bool to test if this is the current month. Use in a conditional like {if current_month} .. {/if}

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}" {if current_month} selected="selected"{/if}>{month_long}</option>
{/card_months}
</select>

have_card_token

If we already have a card token from Stripe (ie. form validation has failed, but we got a token from stripe before hand), we don't need to go off an recreate. Use this to hide your card input, and instead show the secure information on the card, ie. {card_type} and {card_last4}. The card token itself will automatically be added to the form as a hidden variable. Use

{have_card_token}

card_number_dotted

The dotted version of the card, built from {card_type} and {card_last4}.

This will have the correct dots format based on the {card_type}.

{card_number_dotted}

i.e. ···· ···· ···· 4242

card_type

Returns the card type as reported by stripe. ie. 'Visa'. Only available if {have_card_token} is TRUE

{card_type}

card_last4

Returns the last 4 digits of the card. ie. '4242'. Only available if {have_card_token} is TRUE

{card_last4}

have_errors

A bool to test if we have any validation errors on the form. Use it to show your own validation error message.

NOTE: To display Stripe errors add the {exp:charge:error_info} tag to your form!

{have_errors}

error_count

A count of the form errors

{error_count}

errors

A loop of the validation errors. Within the loop we have the following variable.

Show Related Tags

{errors}
    ...
{/errors}

error_message

The error message for the error

{errors}
    {error_message}
{/errors}

error_field_name

Where field_name is any field in your form.

Used to test if any specific field has an error.

{if error_customer_name}
...
{/if}

error_field_name_message

Where field_name is any field in your form.

Used to output the error message associated with a specific field.

{if error_customer_name}
    {error_customer_name_message}
{/if}

Parameters

hash

required

The hash for the transaction to display. This will automatically be added to the return url after a successful payment using the {exp:charge:form} tag.

{exp:charge:info hash="{segment_2}"}

Variables

amount_currency_formatted

The transaction amount, formatted with the currency symbol prefixed.

{amount_currency_formatted}

i.e. $99.00

amount_formatted
also
amount

The transaction amount formatted.

{amount_formatted}

i.e. 99.00

plan_amount

The raw transaction amount in cents (or pence) as we passed through to Stripe.

{plan_amount}

i.e. 9900

type

The transaction type. Will return 'charge' if it was a single payment, 'recurring' if it was a recurring payment.

{type}

either 'charge' or 'recurring'

mode

The mode for the transaction.

{mode}

either 'test' or 'live'

state

The state of the payment. Relevant only to recurring payments, initially will be 'active', but will change to 'canceled' if the user cancels later, or 'expired' if a set length plan that's expired.

{state}

either 'active', 'cancelled' or 'expired'

messages

Added in 1.7.1

An array of messages that are attached to this payment. Useful for third party extensions that may attach their own logic to events, and for returning non-fatal messages. Inside this loop, are the variables {message} and {message_type}

{messages}
    ...
    {message}
    {message_type}
    ...
{/messages}

ended_on

timestamp

The timestamp the payments were canceled on.

Set when the customer cancels a recurring payment or a set length expires. If still active will be '0'.

Accepts date format.

{ended_on}
{ended_on format="%Y-%m-d"}

customer_name

The name of the customer from the payment form.

{customer_name}

customer_email

The email of the customer from the payment form.

{customer_email}

Plan details

If the transaction is recurring, the following variables will also be of use:

plan_wordy

The wordy version of the recurring plan.

{plan_wordy}

i.e. Weekly, Every 3 Months

plan_interval

week, month, year, or blank
Defaults to 'month'

The interval for the recurring payment.

{plan_interval}

i.e. week

plan_interval_count

integer

The number of intervals between payments.

{plan_interval_count}

1 = Recurs every interval
2 = Recurs every other interval
3 = Recurs every third interval
etc.

plan_currency

The currency for the transaction.

Stripe accounts can have multiple currencies enabled at the same time. Check your Stripe account for details.

{plan_currency}

USD, EUR, DKK, etc

plan_currency_symbol

The currency symbol for the transaction.

{amount_currency_formatted} may be more useful depending on your needs

{plan_currency_symbol}

$, €, £, etc.

plan_length_expiry

Added in 1.7

The timestamp when the plan is set to expire for set length plans.

Accepts date format parameter.

{plan_length_expiry format="%Y-%m-d"}

i.e. 'Your plan will expire on
{plan_length_expiry format="%Y-%m-d"}'

plan_length

Added in 1.7

How long the plan will be active for.

The plan will recur every interval for the set length.

{plan_length}

3 = Will recur 3 times
6 = Will recur 6 times

plan_length_interval

Added in 1.7

The interval of how often this set length plan recurs.

If the plan_length was set, this displays the interval that was set with it at payment time.

{plan_length_interval}
week, month, or year

plan_coupon

Added in 1.8

If used, the plan coupon code if any was applied

{plan_coupon}

i.e. 10_OFF

plan_full_amount

Added in 1.8

The full original amount for the payment, in cents (does not include the discount if there was one).

{plan_full_amount}

i.e. 9900

plan_full_amount_formatted

Added in 1.8

The full original amount for the payment, formatted (does not include the discount if there was one).

{plan_full_amount_formatted}

i.e. 9900

plan_full_amount_currency_formatted

Added in 1.8

The full original amount for the payment, formatted with the currency symbol prefixed (does not include the discount if there was one).

{plan_full_amount_currency_formatted}

i.e. 9900

plan_discount

Added in 1.8

The amount discounted from the full amount, in cents.

{plan_discount}

i.e. 3000

plan_discount_formatted

Added in 1.8

The amount discounted from the full amount, formatted.

{plan_discount_formatted}

i.e. 3000

plan_discount_currency_formatted

Added in 1.8

The amount discounted from the full amount, formatted with the currency symbol prefixed.

{plan_discount_currency_formatted}

i.e. 3000

Card details

The following card details are also available:

card_type

The card type used for the payment.

{card_type}

i.e. Visa, Amex etc.

card_exp_month
card_exp_year

The card expiry month/year in numeric format.

{card_exp_month}
{card_exp_year}

i.e. 8 / 2013

card_last4

The final 4 digits on the card used during payment.

{card_last4}

i.e. '4242'

card_number_dotted

The dotted version of the card, built from {card_type} and {card_last4}.

This will have the correct dots format based on the {card_type}.

{card_number_dotted}

i.e. ···· ···· ···· 4242

card_name

The card holder's name, if specified.

{card_name}

i.e. John Tester

card_address_line1
card_address_line2
card_address_city
card_address_zip
card_address_country

The address details for the card, if specified (blank otherwise).

{card_address_line1}
{card_address_line2}
{card_address_city}
{card_address_zip}
{card_address_country}

i.e. 123 Some Street
Suite 1
Some City
12345
US

card_fingerprint

Added in 1.7.1

The unique card fingerprint for this card

{card_fingerprint}

i.e. ly845rEjgK6srC11

Meta details

meta:variable_name

Any meta fields added will be available in the same naming as set on the payment form.

{meta:variable_name}

i.e. {meta:notes}

Stripe details

customer_id

Added in 1.9

The Stripe customer ID for this customer. Will be in the form : cus_xxxxxxxxxxx

{customer_id}

i.e. cus_xxxxxxxxxxx

payment_id

Added in 1.9

The Stripe charge payment ID for this payment. Only avialable on one-time charges.

{payment_id}

i.e. ch_xxxxxxxxxxx

stripe_tag

After every transaction we record the full stripe response object.

All the variables from that response are available here (ie. 'card_fingerprint', 'balance_transaction', 'dispute', 'customer', 'invoice').

These are all prefixed with 'stripe_'.

Checkout the full stripe api documentation to see exactly what is returned.

{stripe_tag}

i.e. {stripe_balance_transaction}

Tag Variables

has_error

boolean

Returns true or false if there is a Stripe API error.

Used in conditionals.

{has_error}

error_message

The error message as returned from the Stripe API.

{error_message}

{exp:charge:error_info}
    {if has_error}
        {error_message}
    {/if}
{/exp:charge:error_info}

Tag Parameters

call

required

The specific endpoint to call, in full.

{exp:charge:api
    call="Stripe_Plan::all"}

{exp:charge:api
    call="Stripe_Invoice::upcoming"}

param_name

If the call requires additional parameters, you can pass them using the param_name and key parameters.

{exp:charge:api
    call="Stripe_Invoice::upcoming"
    param_name="customer"}

key

If the call requires additional parameters, you can pass them using the param_name and key parameters.

{exp:charge:api
    call="Stripe_Invoice::upcoming"
    param_name="customer"
    key="{stripe_subscription_customer}"}

Tag Variables

has_error

boolean

Returns true or false if there is a Stripe API error.

Used in conditionals.

{has_error}

error_message

The error message for the error

{errors}
    {error_message}
{/errors}

data

array

The array of data returned from the api call. Depending on the specific call this will look different. The values from the call will be mapped to variables, so check the Stripe api docs to confirm the exact naming

{data}
    ...
{/data}

Full Example

{exp:charge:api call="\Stripe\Subscription::all" parse="inward" param_name="customer" key="{exp:charge:customer_id}"}
    {if error_message}
        We were unable to retrieve your subscription details.
        

        {error_message}
    {if:else}
        {data}
            ID: {id}

            application_fee_percent: {application_fee_percent}

            billing: {billing}

            billing_cycle_anchor: {billing_cycle_anchor}

            cancel_at_period_end: {cancel_at_period_end}

            canceled_at: {canceled_at}

            created: {created}

            current_period_end: {current_period_end}

            current_period_start: {current_period_start}

            customer: {customer}

            days_until_due: {days_until_due}

            discount: {discount}

            ended_at: {ended_at}

        {/data}
    {/if}
{/exp:charge:api}

Tag Parameters

member_id

optional
defaults to logged in member

The Member ID to find cards for. You can optionally pull the details for a different member by specifying their member_id.

{exp:charge:customer
    member_id="{logged_in_member_id}"}

Tag Variables

count

The number of recorded transactions for the user. This includes both one-off charges and recurring payments.

{count}

charges

A loop of all the recorded transactions, both one-time and recurring. Inside the loop, all the same variables from {exp:charge:info} are available.

{charges}..{/charges}

has_active_recurring

Tests if a user has any "active" or "trialing" recurring payments (NOT subscriptions).
Use like {if has_active_recurring}..{/if}

{has_active_recurring}

recurring

A loop of "active" and "trialing" recurring transactions. Inside the loop, all the same variables from {exp:charge:info} are available.

{recurring}..{/recurring}

count_recurring

The number of "active" and "trialing" recurring transactions.

{count_recurring}

has_inactive_recurring

Tests if a user has any recurring payments with a state other than "active" or "trialing" (NOT subscriptions). Will return true even if the user has an active recurring payment. Use like {if has_inactive_recurring}..{/if}

{if has_inactive_recurring}
    ...
{/if}

inactive_recurring

A loop of the recurring transactions that have a state other than "active" or "trialing". Inside the loop, all the same variables from {exp:charge:info} are available.

{if has_inactive_recurring}
    {inactive_recurring}
        ...
    {/inactive_recurring}
{/if}

count_inactive_recurring

The number of recurring transactions that have a state other than "active" or "trialing".

# Inactive: {count_inactive_recurring}

subscriptions

Loop that list the details of active subscriptions. Inside the loop, the following variables are also available:

Show Related Tags

{subscriptions}
    ...
{/subscriptions}

subscription_member_id

The ID for this member's subscription

{subscriptions}
    {subscription_member_id}
{/subscriptions}

site_id

The site_id for the subscription

{site_id}

timestamp

The timestamp for when the subscription was created

{timestamp}

last_contact

The last contact timestamp from the Stripe api - ie. when we last had an api event for this customer's subscription. Useful for recurring payments etc.

{last_contact}

member_id

The member_id for the subscription

{member_id}

subscription_id

The subscription id

{subscription_id}

status

The status of this subscription.

{status}

customer_id

The Stripe customer_id

{customer_id}

member_group_valid

member_group_invalid

Based on the subscription settings, the member group ids for active and inactive subscriptions

{member_group_valid}

subscription_name

The name of the subscription

{subscription_name}

has_active_subscriptions

Tests if a user has any active Charge subscriptions.
Use like {if has_active_subscriptions}..{/if}

{has_active_subscriptions}

has_inactive_subscriptions

Tests if a user has any old inactive Charge subscriptions. Will return true even if the user has an active Charge subscription.
Use like {if has_inactive_subscriptions}..{/if}

{has_inactive_subscriptions}

subscriptions_count

The number of active subscriptions for the user.

{subscriptions_count}

Parameters

field

optional
string

The field to check against. Corresponds to the fields in the `exp_charge_strip` table. If left blank, this tag will return whether there is any active recurring plan.

{if '{exp:charge:has_active_recurring
    field="meta:subscription_plan" value="Gold Plan"}'}
    Yes!
{if:else}
    No!
{/if}

value

optional
string

The value to check the `field` against. Corresponds to the field values in the `exp_charge_strip` table. If left blank, this tag will return whether there is any active recurring plan.

{if '{exp:charge:has_active_recurring
    field="meta:subscription" value="Gold Plan"}'}
    Yes!
{if:else}
    No!
{/if}

Parameters

member_id

The member_id to pull the Stripe Customer ID for. If none is passed, will return details for the currently logged in member.

{exp:charge:customer_id
    member_id="{logged_in_member_id}"}

Parameters

type

required
string

The action type to perform.

In 1.5 the only valid value is 'end'

{exp:charge:act
    type="end"}

charge_id

required
string

The ID of the charge to act upon.

This will be validated to make sure it is a valid charge, the current user owns that charge, and more details depending on the specific type.

{exp:charge:act
    type="end"
    charge_id="12"}

return

Defaults to current url

The location to return to after a successful action.

Will default to the current url if none passed.

{exp:charge:act
    type="end"
    charge_id="12"
    return="/your/page"}

return_error

Defaults to current url

The location to return to in case of an error while performing the action (i.e. if the validation fails, or the Stripe api is unavailable).

Will default to the current url if none passed.

{exp:charge:act
    type="end"
    charge_id="12"
    return="/your/page"
    return_error="/your/error/page"}

Variables

action_url

The encoded url to trigger the action.

This url is encoded specifically for the member performing the action.

On submit, the values are validated and will only trigger the action if the details pass validation (i.e. subscriptions can only be ended by the member who owns the subscription).

<a href="{action_url}">Continue</a>

Types

end

Ends a recurring payment for a customer.

By default, will immediately end the recurring payments when the user submits, but you can pass an additional parameter to change this.

When a recurring payment is cancelled, this will trigger a Stripe webhook which will end any associated member subscriptions.

Show Related Tags

{exp:charge:act
    type="end"}

Act Parameters

The following parameters can be used inside the {exp:charge:act} tag to modify it's behavior.

at_period_end

Defaults to 'no'

If passed as 'yes', the recurring plan will only cancel at the end of the current period.

This can be useful if you want a user to be able to cancel a membership subscription, but retain their membership up until the date of their next due payment.

{exp:charge:act
    type="end"
    charge_id="12"
    return="/your/page"
    return_error="/your/error/page"
    at_period_end="yes"}

Parameters

member_id

optional
defaults to logged in member

The Member ID to find cards for. You can optionally pull the details for a different member by specifying their member_id.

{exp:charge:cards
    member_id="{logged_in_member_id}"}

customer_id

optional

An alternative way to specify the customer, instead of by member_id.

Useful if you're not requiring members to be logged in.

{exp:charge:cards
    customer_id="{customer_id}"}

Variables

cards_count

The count of active cards. Most likely, 0 or 1, but could be more.

{cards_count}

cards

A loop of the cards associated with their account. All the same card variables available elsewhere are available here, ie. {card_type}, {card_last4}, {card_number_dotted}

{cards}..{/cards}

All parameters are optional on the update_card_form tag :

return

Defaults to current url

The return url to come back to on success.

This will get appended with a transaction hash, used with the {exp:charge:info} tag

{exp:charge:update_card_form
    return="/your/page"}

return_error

Defaults to current url

The location to return to in case of an error while performing the action (i.e. if the validation fails, or the Stripe api is unavailable).

Will default to the current url if none passed.

{exp:charge:update_card_form
    return="/your/page"
    return_error="/your/error/page"}

form_class

string

The class to apply to the form.

{exp:charge:update_card_form
    return="/your/page"
    form_class="form-horizontal"}

form_id

required
string

The ID to apply to the form.
Is used in the javascript setup.

{exp:charge:update_card_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"}

method

post or get

The method to set the form to, defaults to post

{exp:charge:update_card_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    method="post"}

show_card_years_count

integer
defaults to '5'

Used to control how many upcoming years are returned in the {card_years}..{/card_years} tag pair

{exp:charge:update_card_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    show_card_years_count="10"}

Form Inputs

card_number

required
form only

The all important card number. Gets tokenized by the Stripe.js before the server ever sees the value.

<input name="card_number" data-stripe="number" type="text" />

card_cvc

required
form only

The security code for the payment card. Tokenized by stripe.js

<input name="card_cvc" data-stripe="cvc" type="text" />

card_exp_month

required
form only
2 digits

The expiration month on the payment card. Tokenized by stripe.js

<input name="card_exp_month" data-stripe="exp_month" type="text" />

card_exp_year

required
form only
2 or 4 digits

The expiration year on the payment card. Tokenized by stripe.js

<input name="card_exp_year" data-stripe="exp_year" type="text" />

card_name

string

The name on the card.

<input name="card_name" data-stripe="name" type="text" />

card_address_line1

string

The address line 1 for the card holder.

<input name="card_address_line1" data-stripe="address_line1" type="text" />

card_address_line2

string

The address line 2 for the card holder.

<input name="card_address_line2" data-stripe="address_line2" type="text" />

card_address_city

string

The address city for the card holder.

<input name="card_address_city" data-stripe="address_city" type="text" />

card_address_state

string

The address state (of county) for the card holder.

<input name="card_address_state" data-stripe="address_state" type="text" />

card_address_zip

string

The address zip (or postcode) for the card holder.

<input name="card_address_zip" data-stripe="address_zip" type="text" />

card_address_country

2 character country code

The address country for the card holder.

<input name="card_address_country" data-stripe="address_country" type="text" />

Tag Variables

card_years

Defaults to 5 years

List X years to populate the credit card expiration year dropdown.

Years can be altered using the show_card_years_count parameter.

Within the {card_years} loop there are some additional variables to use:

Show Related Tags

{card_years}
    ...
{/card_years}

Card Years Tags

The following tags can be used inside the {card_years} loop to display either 4-digit or 2-digit versions of the years.

You can adjust how many years display by adding/changing the show_card_years_count parameter.

year_long

The year in 4-digit format. Ex: '2016'

<select name="card_exp_year">
{card_years}
    <option value="{year_long}">{year_long}</option>
{/card_years}
</select>

year_short

The year in 2-digit format. Ex: '16'

<select name="card_exp_year">
{card_years}
    <option value="{year_short}">{year_short}</option>
{/card_years}
</select>

card_months

List all the months of the year with tags for the numeric month, the short form of the month name, and the long form of the month name.

Also has a tag for current_month that returns a boolean if the current month in the loop matches the month we're in.

Show Related Tags

{card_months}
    ...
{/card_months}

Card Months Tags

The following tags can be used inside the {card_months} loop to display either the numerical month or the short or long form of the month name.

You can also test the months in the loop agains the {current_month} tag.

month_digit

The digit for the current month, ie. for January return '01'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_long}</option>
{/card_months}
</select>

month_long

Returns the full word for the current month, ie. 'January'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_long}</option>
{/card_months}
</select>

month_short

Returns the short code for the current month, ie. 'Jan'

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}">{month_short}</option>
{/card_months}
</select>

current_month

A bool to test if this is the current month. Use in a conditional like {if current_month} .. {/if}

<select name="card_exp_month">
{card_months}
    <option value="{month_digit}" {if current_month} selected="selected"{/if}>{month_long}</option>
{/card_months}
</select>

have_card_token

If we already have a card token from Stripe (ie. form validation has failed, but we got a token from stripe before hand), we don't need to go off an recreate. Use this to hide your card input, and instead show the secure information on the card, ie. {card_type} and {card_last4}. The card token itself will automatically be added to the form as a hidden variable. Use

{have_card_token}

card_number_dotted

The dotted version of the card, built from {card_type} and {card_last4}.

This will have the correct dots format based on the {card_type}.

{card_number_dotted}

i.e. ···· ···· ···· 4242

card_type

Returns the card type as reported by stripe. ie. 'Visa'. Only available if {have_card_token} is TRUE

{card_type}

card_last4

The final 4 digits on the card used during payment.

{card_last4}

i.e. '4242'

have_errors

A bool to test if we have any validation errors on the form. Use it to show your own validation error message.

NOTE: To display Stripe errors add the {exp:charge:error_info} tag to your form!

{have_errors}

error_count

A count of the form errors

{error_count}

errors

A loop of the validation errors. Within the loop we have the following variable

Show Related Tags

{errors} .. {/errors}

error_message

The error message for the error

{errors}
    {error_message}
{/errors}

error_field_name

Used to test if any specific field has an error.

Where field_name is any field in your form.

{if error_customer_name}
    ...
{/if}

error_field_name_message

Where field_name is any field in your form.

Used to output the error message associated with a specific field.

{if error_customer_name}
    {error_customer_name_message}
{/if}

Usage

{exp:charge:update_card_form}
    ..
    ..all required fields..
    <input type="submit"/>
{/exp:charge:update_card_form}

Parameters

form_id

required
string

The ID to apply to the form.
Is used in the javascript setup.

{exp:charge:update_plan_form
    form_id="charge_form"}

current_plan

required
string

The hash of the associated charge that contains the plan you want to modify.

{exp:charge:customer}
    {if has_active_subscriptions}
        {subscriptions}
            {exp:charge:update_plan_form
                form_id="charge_form"
                current_plan="{hash}"}
                    ...
            {/exp:charge:update_plan_form}
        {/subscriptions}
    {/if}
{/exp:charge:customer}

form_class

string

The class to apply to the form.

{exp:charge:update_plan_form
    form_id="charge_form"
    form_class="form-horizontal"}

return

Defaults to current url

The return url to come back to on success.

This will get appended with a transaction hash, used with the {exp:charge:info} tag

{exp:charge:update_plan_form
    return="/your/page"}

return_error

Defaults to current url

The location to return to in case of an error while performing the action (i.e. if the validation fails, or the Stripe api is unavailable).

Will default to the current url if none passed.

{exp:charge:update_plan_form
    return="/your/page"
    return_error="/your/error/page"}

method

post or get

The method to set the form to, defaults to post

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    method="post"}

plan_amount

required
numeric

The payment amount. Can be a fixed value in the {exp:charge:form} tag or as an editable input field.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_amount="65"}

<input name="plan_amount" value="65" type="text" />

on_success

action_shortname

Short Name of Charge Action you want to trigger after a successful transaction. More info on Charge Actions here.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    on_success="your_action"}

on_success:variable_name

string

Used to supply extra information to Charge Actions to specify entry_id or url_title and any additional fields.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    on_success="update_entry_action"
    on_success:entry_id="3"
    on_success:url_title="my_entry"
    on_success:my_custom_field="awesome"
    on_success:member_fav_food="pizza"}

Form Inputs

plan_amount

required
numeric

The payment amount. Can be a fixed value in the {exp:charge:form} tag or as an editable input field.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_amount="65"}

<input name="plan_amount" value="65" type="text" />

plan_currency

string
Defaults to Stripe Currency

The currency to process the transaction in.

Defaults to the default currency in your Stripe account.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_currency="USD"}

plan_interval

recurring
week, month, or year
Defaults to 'month'

The interval of how often this plan recurs. Used in conjunction with plan_interval_count

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_interval="week"}

plan_interval_count

recurring
numeric

Optional, must be numeric if passed. If not passed, defaults to '0'. '0' is treats the payment as a one-off charge. Any other (valid) number is used as the count of the intervals, ie. 'every 3 months'.

{exp:charge:update_plan_form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    plan_interval="week"
    plan_interval_count="6"}

Tag Variables

card

The details of the payment card currently active for the customer. Within this loop the following details are available

Show Related Tags

{card}
    ...
{/card}

card_type

Returns the card type as reported by stripe. ie. 'Visa'. Only available if {have_card_token} is TRUE

{card}
    {card_type}
{/card}

card_last4

Returns the last 4 digits of the card. ie. '4242'. Only available if {have_card_token} is TRUE

{card}
    {card_type}
    {card_last4}
{/card}

card_exp_month

The card month expiry

{card}
    {card_type}
    {card_last4}
    {card_exp_month}
{/card}

card_exp_year

The card year expiry

{card}
    {card_type}
    {card_last4}
    {card_exp_month}
    {card_exp_year}
{/card}

card_number_dotted

The dotted version of the card, built from {card_type} and {card_last4}.

This will have the correct dots format based on the {card_type}.

{card_number_dotted}

i.e. ···· ···· ···· 4242

have_errors

A bool to test if we have any validation errors on the form. Use it to show your own validation error message.

NOTE: To display Stripe errors add the {exp:charge:error_info} tag to your form!

{have_errors}

error_count

A count of the form errors

{error_count}

errors

A loop of the validation errors. Within the loop we have the following variable

Show Related Tags

error_message

The error message for the error

{errors} .. {/errors}

error_field_name

Used to test if any specific field has an error.

Where field_name is any field in your form.

{if error_customer_name}
    ...
{/if}

error_field_name_message

Where field_name is any field in your form.

Used to output the error message associated with a specific field.

{if error_customer_name}
    {error_customer_name_message}
{/if}

Usage

{exp:charge:update_plan_form}
    ..
    ..all required fields..
    <input type="submit"/>
{/exp:charge:update_plan_form}