Charge Upgrade Documentation

Tags

These terms are used throughout the documentation:
required: This parameter/field is required for this tag to function.
form only: This can only be set as a field in the form and not as a parameter in the tag.
param only: This parameter can only be set in the tag and not as a field in the form.
fixed value: This field cannot be edited and is set with a fixed value.
recurring only: This parameter/field only applies to recurring charges.
one-time only: This parameter/field only applies to one-time charges.
added in X.X.X: This parameter/field is only available from this version forward.
logged in: This tag is only available if the user is logged in.

Charge has the following front-end tags.

{exp:charge:form}
The primary tag to create your payment form. This will wrap the output in the required form elements. You'll still need to include the require inputs within.
{exp:charge:stripe_js}
A tag to output the path to the stripe javascript library.
{exp:charge:js}
A tag to output the path to the charge javascript library.
{exp:charge:public_key}
This tag outputs the public key for your stripe account. It automatically takes into account the current account setting
{exp:charge:info}
A tag to display the information about a transaction. Great for use on a thanks page, or a linked receipt page.
{exp:charge:error_info}
A tag to output any error messages returned from the Stripe api. Useful on the 'return_error' template.
{exp:charge:api}
A tag to call any of the Stripe api endpoints, useful if you need to do more advanced things
{exp:charge:customer}
A tag to get all of a customer's recorded transactions
{exp:charge:has_active_recurring}
A shortcut to check if a specific recurring payment is active
{exp:charge:act}
A tag to let a customer perform actions on their payments. Pair with the :customer tag to make a customer dashboard
{exp:charge:cards}
A tag to list all the active cards against a customer, directly pulled from the Stripe api
{exp:charge:update_card_form}
A tag to create a form to allow your customers to change the card they have on record for any future payments
{exp:charge:update_plan_form} New in 1.10.0
A tag to create a form to allow your customers to update their active payment plans, mid-cycle.

{exp:charge:form}

The primary tag to create your payment form. This will wrap the output in the HTML <form> </form> elements. You will still need to include the required parameters/fields.

Most of the parameters/fields can be placed in EITHER the {exp:charge:form} tag OR as an input field in the form itself (unless otherwise noted as 'param only' or 'form only').

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.

{exp:charge:form
    return="/your/page"
    form_class="form-horizontal"
    form_id="charge_form"
    create_member="yes"}
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"}

Form Input Fields

The form inputs breakdown into 4 groups: customer, plan, card, and meta

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
NOTE: Don't forget to add the Stripe data-stripe="field_name" tags to your form fields.
Read more about the Stripe Javascript setup.
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 fields are a free for all. Any field with the prefix meta: will be recorded against the transaction. You can use meta fields to add extra data you might need to collect. Meta fields are concatenated into a csv string and passed along to Stripe too.

NOTE: You can have up to 20 meta: fields, with field names up to 40 characters long and values up to 500 characters long.
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

Within the form tag, there are number of variables available to you for simplifying the form setup, and error state population.

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:

{card_years}
    ...
{/card_years}
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.

{card_months}
    ...
{/card_months}
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.

{errors}
    ...
{/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}

{exp:charge:stripe_js}

This tag simply outputs the path to the included stripe javascript library script, ie.

<script src="{exp:charge:stripe_js}"></script>

Would output similar to:

<script src="/path/to/your/themes/third/party/charge/stripe.js"></script>

{exp:charge:js}

This tag outputs the path to our charge javascript function. This uses jquery, but could be adjusted to work with native javascript methods if needed. Once added to the page, the .charge() method will be available.

<script src="{exp:charge:js}"></script>

Would output similar to:

<script src="/path/to/your/themes/third/party/charge/jquery.charge.js"></script>

Note: The Charge js library expects two values to be passed, the payment form id (which defaults to 'charge-form') and the stripe error message container id, which in our examples are called 'payment-errors'. See the demo templates to see usage.

{exp:charge:public_key}

This tag is useful to output your Stripe public key on your front-end javascript. It'll automatically return the appropriate key based on the current account setting, ie Live vs. Test. Use it in your front-end javascript like so :

Stripe.setPublishableKey('{exp:charge:public_key}')

{exp:charge:info}

A tag to output the information about a transaction. Useful on a thanks page or online receipt page. All transaction details are pulled based on a 'hash', which is the only required param on the tag.

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

We store some direct information about the stripe records so you can later tie things back as needed.

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

Additionally we store the full data returned from stripe in a full array. If you need it you can access those values like:

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}

Note: Depending on the transaction type (one-off vs. recurring) and the Stripe api version you're running, the specific values returned here may change. Check out the full stripe docs and any api changelogs if you experience difficulties.

{exp:charge:error_info}

A tag to output any error message as returned from the Stripe api. Designed to be used on the error template, as set in the 'return_error' param on the :form tag. There are no parameters, and only the one variable.

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}

{exp:charge:api}

A tag to let you call any of the Stripe api endpoints. From the full Stripe API Documenation you can use the :api tag to call any of those calls. This is mostly useful for when you might want to pull the latest information from the api, or access extra data about a charge, or customer, that we might not have directly available.

For example - this can be used with the 'Stripe::upcoming' call, to find a certain customer's upcoming invoice details, their date and value.

Note: When using this call, be sure to check for a valid response using the 'has_error' variable. This tag calls the api directly on each load, and these calls can potentially fail

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}

{exp:charge:customer}

A tag to let you pull all of the transactions for a specific member. If no member_id parameter is specified, it will return just the current user's transactions. Inside the tag, the {charges}..{/charges} loop is really the same as the {exp:charge:info} tag, and has the same functions.

You can also test to see if the user has any active or expired subscriptions.

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:

{subscriptions}
    ...
{/subscriptions}
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}

{exp:charge:has_active_recurring}

A tag to check if a customer has a specific active recurring plan. It will return a boolean true/false.

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}

{exp:charge:customer_id}

A tag to get the customer's Stripe Customer ID. It will return the ID in the format of cus_XXXXXXXXXX.

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

{exp:charge:act}

A tag to let users perform actions upon their (recurring) payments. Added in 1.5, this currently only has the option to let users cancel their recurring payments, but will be expanded later to include other options.

Additionally the type and customer details will be validated, if the action isn't valid (ie. attempting to 'end' a non-recurring payment) a {no_results} condition will be returned instead of the tag contents.

When a recurring payment is canceled, it's {state} value changes from 'active' to 'canceled', and the {ended_on} variable gets the current timestamp.

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

The :act tag will have various action types. Initially in Charge 1.5, the only option is 'end'. Later other options will be added.
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.

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

Example

An example of usage, within the :customer tag, to let a user cancel their recurring payments

{exp:charge:customer}
    {if has_active_recurring}
        <h3>You have {count_recurring} recurring payments</h3>

        {recurring}
            <p>{amount_currency_formatted} - {plan_wordy}</p>

            {exp:charge:act type="end" charge_id="{id}" at_period_end="yes"}
                <a href="{action_url}">Cancel this recurring payment</a>
            {/exp:charge:act}
        {/recurring}
    {/if}
{/exp:charge:customer}

Which will return similar to:

<h3>You have 1 recurring payments</h3>

<p>$10.00 - Weekly</p>
<a href="http://site.com/?ACT=xx...">Cancel this recurring payment</a>

When the customer clicks that link, the details are all validated again, to make sure that only this customer can act on their payments, then their recurring payment will be canceled at the end of the current period (because we passed the 'at_period_end="yes" parameter').

Note: More action types will be added in further releases to allow customer to fully self-manage their payments direct from the site front-end. If you require any specific actions, email help@eeharbor.com and we'll help you out.

{exp:charge:cards}

A tag that queries the Stripe api for a full list of all the cards associated with a customer's account.

Note: While Charge currently only deals with a single card per-customer, Stripe does allow multiple cards. Our methods don't assume they'll just have a single card returned against their account, but if you're only interacting with Stripe via Charge, they'll only have ever have one card.

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}

Note: This tag directly calls the Stripe api to make sure we're pulling the up-to-date information. It's designed to be used within a dashboard-type area.

{exp:charge:update_card_form}

The Update Card Form, lets you give users the option to change the card they have on record, outside the normal payment flow. By updating their card, we'll remove any other cards against their account, and replace it with this new one. Any active recurring payments will then be taken from this new card for any future payments.

The form itself works very much like the main {exp:charge:form} tag, but requires only the card inputs.

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

Within the form tag, there are number of variables available to you for simplifying the form setup, and error state population.
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:

{card_years}
    ...
{/card_years}
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.

{card_months}
    ...
{/card_months}
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

{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

The simplest usage of the tag is like so:

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

Note: Like the :form tag, you'll need to include the required Charge javascript tags on the page to let Stripe handle the card details.

{exp:charge:update_plan_form}

The Update Plan Form, lets you give your users the option to update their payment plans mid-cycle. By updating their payment plans, you can allow the customers to move their subscriptions, alter their payment amounts and payment intervals.

As well as altering all their payment details, this will allow you to trigger actions in exactly the same way the standard payment form.

The form itself works very much like the main {exp:charge:form} tag, but requires only the plan inputs. All other details are resused from their active plan.

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

Just like on the {exp:charge:form} tag all these values can be as either parameters or inputs on the form.

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

Within the form tag, there are number of variables available to you for simplifying the form setup, and error state population.
card

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

{card}
    ...
{/card}
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

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

The simplest usage of the tag is like so:

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

Note: Because this form submits directly without any new card details, you don't need the Charge/Stripe.js to trigger against this form.

Support

Having problems setting up and/or using Charge Upgrade? Support is offered from 10am to 4pm EST weekdays. Send us an email at help@eeharbor.com and we will respond as quickly as we can.