Tags
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: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
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.
Tag Parameters
All parameters are optional on the form tag :
return- The return url to come back to on success. This will get appended with a transaction hash, used with the
{exp:charge:info} tag
return_error- The return url to come back to after posting on the event of an error other than validation fail. Validation fails will return to the current url with the errors available as variables
form_class- The class to apply to the form
form_id- The id to apply to the form
method- The method to set the form to, defaults to post
show_card_years_count defaults to '5'- Used to control how many upcoming years are returned in the {card_years}..{/card_years} tag pair
on_success- Used to trigger actions after a successful transaction
on_success:..- Used to supply extra information to actions. Used with Entry Actions to specify entry_id or url_title and any additional fields
create_member yes or no- Optionally create a member on success. Only applies to non-logged in members, defaults to no. With this option you can also allow users to choose if they want an account, and if they want to supply a password in the same form. The created account will have the details from the customer inputs, and they will be immediately logged in.
- `plan_trial_days` Defaults to '0', must be numeric
- Optional way to set a 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.
plan_balance Defaults to '0', must be numeric, only used on recurring payments- Optional way to set an account balance for the customer. You can use this to take an extra one-time charge from a customer on the first payment of a recurring plan. Great if you need to take a one-time setup fee in addition to the recurring amount. You can also pass negative values and have that value discounted from the customer's invoices. The discount amount will roll over if it's greater than the invoice amount. This balance amount is only used for recurring payments and is ignored on one-time charges. For safety this value can only be set directly as a parameter on the form tag, not via any form inputs.
plan_length Numeric, the number of periods to keep active, optional- Used to define a set length for any subscriptions or recurring payments. ie. '3' gives a plan length of 3 months. The interval can be adjusted using the plan_length_interval param. Learn more about how set length plans work
plan_length_interval 'week', 'month', or 'year', optional - only used if you want to have a set length plan- 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.
plan_set_name optional Added in 1.8.3- Optionally give your plan a specific name in place of the automatically generated name based on the plan parameters. ie. plan_set_name="Gold Plan", instead of "$50 Monthly"
required pipe seperated list - ie. 'field_one|field_two|field_three'- An optional parameter to add extra fields to the validation logic to make them required. Also works directly on any 'meta:..' fields you might have added. Be sure to add the appropriate
{error_field_name_message} tags to output your new validation messages.
-
Form Inputs
The form inputs broadly breakdown into 4 groups : customer, plan, card, and meta fields.
Customer Fields
customer_name *required- The name of the customer
customer_email *required- The email of the customer. This gets used to identify the customer on the Stripe side
Plan Fields
plan_amount *required, double- The payment amount. Must be numeric, gets converted to cents/pennies, so ($)75 is treated like 7500 cents.
plan_currency- Optional, defaults to the default currency on your Stripe account.
plan_interval- Optional, defaults to Monthly. Valid values are
week, month, or year.
plan_interval_count- 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'.
plan_coupon- Optional. If passed is validated against coupons on record. If valid for the payment in question, will apply the discount directly, otherwise will return an error
Card Fields
card_number *required- The all important card number. Gets tokenized by the Stripe.js before the server ever sees the value.
card_cvc *required- The CVC for the card. Tokenized by stripe.js
card_exp_month *required- The expiry month on the card. Tokenized by stripe.js
card_exp_year *required- The expiry year on the card. Tokenized by stripe.js
card_name- The name on the card.
card_address_line1- The address line 1 for the card holder.
card_address_line2- The address line 2 for the card holder.
card_address_city- The address city for the card holder.
card_address_state- The address state (of county) for the card holder.
card_address_zip- The address zip (or postcode) for the card holder.
card_address_country- The address country for the card holder.
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.
meta:* where * is any value you specify- The value of the {meta:*} input passed. ie. Pass a field named 'meta:language', and the variable {meta:language} will be populated
Member Fields
If the create_member = 'yes' option is passed to the form, Charge can create a new member account during payment. The created member will only be created if the user isn't currently logged in. When created the member will be added to the default site member group and immediately logged in. This can be especially useful if you want to create + 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.
Optionally you can give your users the chose wether they want to create an account, and if they want to supply a password as part of this form.
member_create- Lets the user disable the member creation. Only used if the 'create_member="yes"' param has been passed on the form. Defaults to 'yes', pass 'no' to disable
member_password and member_password_confirm- Optionally 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. In that case you'll need to provide a mechanism to allow a new user to reset their password.
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} .. {/card_years}- This will list the next X years for populating your years card dropdown. Defaults to the next 5 years, but can be altered using the '
show_card_years_count' parameter. Within the {card_years} loop there are some additional variables to use :
year- The year in the form similar to '2013'
year_short- The year in the short form similar to '13'
{card_months} .. {/card_months}- This is a loop to help create your month drop down. Will list all 12 months, along with their various numerical and worded options, along with a variable to specify the current month.
month_digit- The digit for the current month, ie. for January return '01'
month_long- Returns the full word for the current month, ie. 'January'
month_short- Returns the short code for the current month, ie. 'Jan'
current_month- A bool to test if this is the current month. Use in a conditional like {if current_month} .. {/if}
{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
{card_number_dotted}- The card number in a format like : '···· ···· ···· 4242'. The format of the dots will reflect the proper format based on the {card_type}
{card_type}- Returns the card type as reported by stripe. ie. 'Visa'. Only available if {have_card_token} is TRUE
{card_last4}- Returns the last 4 digits of the card. ie. '4242'. Only available if {have_card_token} is TRUE
{have_errors}- A bool to test if we have any validation errors on the form. Use it to show your own validation error message.
{error_count}- A count of the form errors
{errors} .. {/errors}- A loop of the validation errors. Within the loop we have the following variable :
{error_message}- The error message for the error
{error_[field_name]} where [field_name] is any field in your form- Used to test if any specific field has an error. ie. For the field 'customer_name' : {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. ie. For the field 'customer_name' : {error_customer_name_message}
Usage
The simplest usage of the tag is like so:
{exp:charge:form}
..
..all required fields..
<input type="submit"/>
{/exp:charge:form}
{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.
Variables
{amount_currency_formatted} ie. $99.00- The transaction amount, formatted with the currency symbol prefixed.
{amount_formatted} also {amount} ie. 99.00- The transaction amount formatted.
{plan_amount} ie. 9900- The raw transaction amount in cents (or pence) as we passed through to Stripe.
{type} either 'charge' or 'recurring'- The transaction type. Will return 'charge' if it was a single payment, 'recurring' if it was a recurring payment.
{mode} either 'test' or 'live'- The mode for the transaction.
{state} either 'active', 'canceled' or 'expired'- 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.
{messages}..{/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}
{ended_on} timestamp, use format=".." parameters
- 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'.
{customer_name}{customer_email}- The values for the customer as passed on the payment form
Plan details
If the transaction is recurring, the following variables will also be of use:
{plan_wordy} eg. Weekly, Every 3 Months- The wordy version of the recurring plan.
{plan_interval} either 'week', 'month', 'year' or blank- The interval for the recurring payment.
{plan_interval_count} integer value- The number of intervals between payments. '1' indicates recurs every interval, '3' every third interval etc..
{plan_currency} eg. USD- The currency for the transaction. (Stripe accounts can have multiple currencies enabled at the same time. Check your Stripe account for details)
{plan_currency_symbol} eg. $- The currency symbol for the transaction. (
{amount_currency_formatted} may be more useful depending on your needs)
{plan_length_expiry} Added in 1.7- If a set length plan, the timestamp of when the plan is set to expire. ie. 'Your Plan will expire on
{plan_length_expiry format="%Y-%m-d"}'
{plan_length} Added in 1.7{plan_length_interval} Added in 1.7- If a set length plan, the details of the plan length as defined at payment time.
{plan_coupon} Added in 1.8- The plan coupon if any was applied
{plan_full_amount} Added in 1.8- The full original amount for the payment if there was a discount applied
{plan_discount} Added in 1.8- The amount discounted from the full amount
Card details
The following card details are also available:
{card_type} eg. Visa, Amex etc..- The card type
{card_exp_month}{card_exp_year}- The card expiry month/year in numeric format. ie. 8 / 2013
{card_last4} eg. '4242'- The final 4 digits on the card
{card_number_dotted} eg. ···· ···· ···· 4242- 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_name} optional- The card holder's name if specified
{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_fingerprint} Added in 1.7.1- The unique card fingerprint for this card
Meta details
{meta:...} - eg. {meta:notes}- Any meta fields added will be available in the same naming as set on the payment form.
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 of the form : cus_xxxxxxxxxxx
{payment_id} Added in 1.9- The Stripe charge payment id for this payment. Will be of the form : ch_xxxxxxxxxxx. Note - this will only be directly avialable on one-time charges
Additionally we store the full data returned from stripe in a full array. If you need it you can access those values like :
{stripe_..}- 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.
In general usage, you'll probably never need it, but just in-case, we keep the full stripe response object for you query against:
{stripe_..}- 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.
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
{error_message}- The error message as returned from the Stripe API
{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 Paramters
call *required- The specific endpoint to call, in full. ie. 'call="Stripe_Plan::all"', or 'call="Stripe_Invoice::upcoming"'.
param_namekey- If the call requires additional parameters, you can pass them using these paramters. ie for Stripe_Invoice::upcoming, this would be 'key="{stripe_subscription_customer}" param_name="customer"'
Tag Variables
{has_error}- Used to see if the api returned an error
{error_message}- If there was an error, the message we got back
{data}..{/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
{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 Paramters
member_id- The member_id to pull the records for. If none is passed, will return details for the currently logged in member.
Tag Variables
{count}- The number of recorded transactions for the user
{charges}..{/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.
{recurring}..{/recurring}- A loop of just the recurring transactions. Inside the loop, all the same variables from {exp:charge:info} are available.
{has_active_subscriptions}{has_inactive_subscriptions}- Variables to test if a user has any active or inactive subscriptions. Use like {if has_active_subscriptions}..{/if}
{subscriptions}..{/subscriptions}- Loops that list the details of each subscription. Inside the loops, the following variables are also available :
{subscription_member_id}- The id for this member's subscription
{site_id}- The site_id for the subscription
{timestamp}- The timestamp for when the subscription was created
{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.
{member_id}- The member_id for the subscription
{subscription_id}- The subscription id
{status}- The status of this subscription.
{customer_id}- The Stripe customer_id
{member_group_valid}{member_group_invalid}- Based on the subscription settings, the member group ids for active and inactive subscriptions
{name}- The name of the subscription
{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- The action type to perform. In 1.5 the only valid value is 'end'
charge_id required- 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.
return- The location to return to after a successful action. Will default to the current url if none passed.
return_error- The location to return to in case of an error while performing the action. ie. if the validation fails, or the Stripe api is unavailable. Will default to the current url if none passed.
*extra parameters* optional- Depending on the action type, you can pass additional parameters to alter default behaviors
Variables
{action_url}- The encoded url to trigger the action. This url is encoded directly the member in question. On submit the values are validated, and will only trigger the action if the details pass validation. ie. subscriptions can only be ended by the member who owns the subscription
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 canceled, this will trigger a Stripe event which will end any associated member subscriptions.
at_period_end optional- Defaults to 'no', pass 'yes' to change the cancel behavior. 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.
reactivate- Reactivates a cancelled recurring payment for a customer. Very useful when paired with the 'end' type action, and the 'at_period_end' is set to yes. A great way to present a 'Changed your mind?' style option.
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 {recurring_count} 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 support@squarebit.co.uk 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 the currently 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.
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.
Variables
{card_count}- The count of active cards. Most likely, 0 or 1, but could be more.
{cards}..{/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}
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.
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- The return url to come back to on success. This will get appended with a transaction hash, used with the
{exp:charge:info} tag
return_error- The return url to come back to after posting on the event of an error other than validation fail. Validation fails will return to the current url with the errors available as variables
form_class- The class to apply to the form
form_id- The id to apply to the form
method- The method to set the form to, defaults to post
show_card_years_count defaults to '5'- Used to control how many upcoming years are returned in the {card_years}..{/card_years} tag pair
Form Inputs
card_number *required- The all important card number. Gets tokenized by the Stripe.js before the server ever sees the value.
card_cvc *required- The CVC for the card. Tokenized by stripe.js
card_exp_month *required- The expiry month on the card. Tokenized by stripe.js
card_exp_year *required- The expiry year on the card. Tokenized by stripe.js
card_name- The name on the card.
card_address_line1- The address line 1 for the card holder.
card_address_line2- The address line 2 for the card holder.
card_address_city- The address city for the card holder.
card_address_state- The address state (of county) for the card holder.
card_address_zip- The address zip (or postcode) for the card holder.
card_address_country- The address country for the card holder.
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} .. {/card_years}- This will list the next X years for populating your years card select. Defaults to the next 5 years, but can be altered using the '
show_card_years_count' parameter. Within the {card_years} loop there are some additional variables to use :
year- The year in the form similar to '2013'
year_short- The year in the short form similar to '13'
{card_months} .. {/card_months}- This is a loop to help create your month drop down. Will list all 12 months, along with their various numerical and worded options, along with a variable to specify the current month.
month_digit- The digit for the current month, ie. for January return '01'
month_long- Returns the full word for the current month, ie. 'January'
month_short- Returns the short code for the current month, ie. 'Jan'
current_month- A bool to test if this is the current month. Use in a conditional like {if current_month} .. {/if}
{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
{card_number_dotted}- The card number in a format like : '···· ···· ···· 4242'. The format of the dots will reflect the proper format based on the {card_type}
{card_type}- Returns the card type as reported by stripe. ie. 'Visa'. Only available if {have_card_token} is TRUE
{card_last4}- Returns the last 4 digits of the card. ie. '4242'. Only available if {have_card_token} is TRUE
{have_errors}- A bool to test if we have any validation errors on the form. Use it to show your own validation error message.
{error_count}- A count of the form errors
{errors} .. {/errors}- A loop of the validation errors. Within the loop we have the following variable :
{error_message}- The error message for the error
{error_[field_name]} where [field_name] is any field in your form- Used to test if any specific field has an error. ie. For the field 'customer_name' : {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. ie. For the field 'customer_name' : {error_customer_name_message}
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.
