Templating Reference

The primary way you'll be interacting with Charge is through front-end templating.

The following methods and variables are available for your templates. Specific usage and where and how to use these methods and variables are available through the documentation.

Setting the Payment Form

setPaymentOptions
Sets the payment options for a request
setCheckoutOptions
Sets the payment options for a checkout payment request

Getting Charges

customer
Returns a customer model for a User. The customer element will have all the current state and Charges for a user.
charges
Returns an element criteria for a set of Charges.
getChargesByUser
Returns an array of Charges for a specific user.
getChargeByHash
Returns a specific Charge by the charge hash.

Getting Stripe Settings

getPublicKey
Returns the public key for the current mode
getMode
Returns the current mode. ie. test or live

setPaymentOptions #

Used to set all the payment options for a request. This is required on all payment forms, except those using Stripe Checkout, where the setCheckoutOptions tag is used.

The setPaymentOptions tag takes an array of details for the payment request and encrypts them using the Craft install's encryption key, and includes the encrypted details on the form as a hidden input called opts.

The payment options are the primary way you'll set up your payment forms.

set Payment Options usage and details

{{ craft.charge.setPaymentOptions({
       'planAmount' : 99.99
}) }}

setPaymentOptions is key It's how the front-end templates securely talk to the backend controllers.


setCheckoutOptions #

This tag is a variant of the setPaymentOptions method, and accepts all the same options.

The primary difference is that the checkout options method instead setups the payment options to use Stripe Checkout for payment, and also returns a fully ready to use checkout button, as well as the hidden and encrypted opts input.

You can use the setCheckoutOptions method to get going amazingly quickly as it will also include all the nessecary javascript components, removing the need to include stripe.js and jquery.charge.js.

set Checkout Options usage and details

{{ craft.charge.setCheckoutOptions({
       'planAmount' : 99.99
}) }}

setCheckoutOptions is great for getting started It fully sets up all the required parts, javascript included in a single tag. Make sure you check the full usage details to get the most out of the behaviour options


customer #

Returns the Charge customer model for a user.

The customer model is very useful for getting all the charges and associated actions or details from a logged in user.

If the user is not logged in, or does not have a Charge customer associated with the user account, it will return null.

The customer model is also where any saved payment cards will be associated, and can be used as part of the payment forms to offer an option to reuse saved cards.

Customer model usage and details

{% set customer = craft.charge.customer %}
{% if customer %}
   Here are all your charges.
   {% for charge in customer.charges %}
      ...
   {% endfor %
{% endif %}

charges #

Returns an element criteria of the Charge element. This standard element criteria can be adjusted with extra parameters and options just like the entry element criteria.

Without any parameters, the charges element criteria will return all charges across all customers. It's primary use is for custom admin areas or otherwise filtered display.

To just show the current users's charges, instead use the getChargesByUser tag, which limits things to the current user.

{% set allCharges = craft.charge.charges %}

{% for charge in allCharges %}
   Payment for {{ charge.amountFormatted }}, by {{ charge.customer.email }}
{% endfor %}

This returns all charges Be careful using this tag in public templates. If you want to show just a specific Charge, or a specific user's Charges, use getChargeByHash and getChargesByUser respectively


getChargesByUser #

Returns an array of Charges for the currently logged in user.

This method is very useful for listing out all the Charges for a user. If the current user is not logged in, or does not have any associated Charges, this method will return an empty array.

Each item in the array will be a Charge Model.

{% set userCharges = craft.charge.getChargesByUser %}

{% if userCharges %}
   You have {{ userCharges | length }} Charges.

   {% for charge in userCharges %}
      ..
   {% endfor %}
{% else %}
 You have no payments on record
{% endif %}

getChargeByHash #

Parameters

hash required
The unique hash string for the Charge model to find.

This method returns a specific Charge model, based on a hash value.

Each Charge has a unique random string called it's hash. This is used to safely link to receipt pages, and can be used to uniquely find a Charge. This is hash method works for both users and guests.

If the hash isn't valid, returns null.

{% set charge = craft.charge.getChargeByHash( craft.request.getSegment3 ) %}

{% if charge %}
   Thank you for your payment of {{ charge.amountFormatted }}
{% endif %}

Set the template + Charge element path in the general settings By setting the path for Charge elements, and the template to use, you can skip the requirement to pull a charge directly using this method. This works in exactly the same way the Entry templates work. Simply visiting a charge's url will automatically add the Charge model variable to the current context for the template.


getPublicKey #

Returns the public key for the current mode. eg. 'pk_xxxxxxxxxxxxxx', or an empty string if the key for the current mode is not set.

This is most commonly used part of the js init block to set the public key for the Stripe js.

$(function() {
    Stripe.setPublishableKey('{{ craft.charge.getPublicKey }}');
    $(this).charge();
});

getMode #

Returns the current mode Charge is running in. Can be live or test.

{% if craft.charge.getMode == 'test' %}
   Currently in Test Mode
{% endif %}

Stripe Connect is hidden in normal usage It's only designed for use on more complex setups with multi-vendor sellers. If you need Connect on your site, get in touch for details on how to set it up

isConnectEnabled #

Returns a bool true / false on if Connect is enabled on this install.

{% if craft.charge.isConnectEnabled %}
   Connect is enabled
{% endif %}