Charge Model

The Charge Model is the primary way you'll interact with Charge in your templates.

On the payment page we build up a Charge Model which holds all the details about the payment. It's what all the customer details, payments, and extra data are all attached to. It's the key part of the whole system.

The Charge Model is also a fully fledged Craft Element, with all that comes with that. It's related to User that created it (if the customer was logged in when the Charge was created) and has further relationships for Payments, Customer and more.

On Charge detail pages, you'll have the charge model automatically available. You can also get a specific charge like craft.charge.getChargeByHash(..) and all charges for the current user user like craft.charge.getChargesByUser().


Getting a Charge Model

Use the Element Routing! In the Charge > Settings > General, you can set the element routing and element template. When you've set that you can just use the same setup as with craft's entries, and simply visiting the url of a charge (ie. via. {{ charge.url }} ) will get the correct charge available on the page context. It's really useful.

Getting a Charge model is the first step to showing information about it in your templates. You can get a specific charge, charges by a user, or all charges, using the following approaches :

craft.charge.getChargeByHash( hash )
Get's a charge by a specific hash. This can be useful if you're linking charges in the url and manually building up your urls. An example of usage would use a url of a format similar to /thanks/{{ hash }}. In that case you'd do something like :
{% set charge = craft.charge.getChargeByHash( craft.request.getSegment(2) ) %}

{% if charge %}
  .. details on the charge
{% endif %}
craft.charge.getChargesByUser( userId ) Array
Gets all the charges for a user. If you don't pass in an userId value, this will return charges for the current user. Will return an empty array if the user has no charges, or is a guest.
{% set charges = craft.charge.getChargesByUser %}

{% if charges %}
   You have the following Charges ..

    {% for charge in charges %}
      .. Details..
    {% endfor %}
{% else %}
   You have no Charges
{% endif %}

Related Models

The Charge model itself contains very little direct information. Most of the information useful in your templates are held in related models. You can access these using the following attributes on the charge model :

payments Array of Charge_PaymentModels
An array of related Charge Payment Models for this Charge. Each item in this array relates to a specific separate payment. This is especially useful for recurring Charges. Can be an empty array if no payments have been made.
customer Charge_CustomerModel
The Charge Customer Model for the Charge. Every charge will have an associated customer model, which is where details like customer email and name are stored. This maps cleanly to the Stripe customer, and is used to allow returning users to easily reuse their details.
subscription Charge_SubscriptionModel
The Charge_SubscriptionModel for a recurring Charge. This holds all the up-to-date details about a recurring payment, including the next payment date, current status etc..
account Charge_AccountModel
The Charge_AccountModel is used as part of the Connect feature. If a charge was sent to a connected sub-account, the account model will have the details of that account.

Attributes

The following attributes are directly available on the Charge model.

id Number
The id for the charge.
hash String
The unique hash for the charge. This is safe to expose on the front-end for receipts.
type String
Returns one-off or recurring, depending on if the charge is one off, or recurring.
uri String
The uri for this charge element. Will vary depending on the settings defined in the Charge > Settings > General
url String
The full url for this charge element. Will vary depending on the settings defined in the Charge > Settings > General
userId Number
The user id of the owner of the Charge. This can be null if the charge was created by a guest.
payment Charge_PaymentModel
Just the first Charge Payment Model for a Charge. This is useful if you're using just one-time payments with your setup. Equivalent to the first item in the payments array. Can be null if no payments have been made.
customerId Number
The customer id of the owner of the Charge. This refers to the Charge Customer Model. You can cleanly access this by the customer method on the model.
mode String
The Stripe mode the transaction was made in - test or live.
sourceUrl String
The original url the charge was triggered on your site.
request Array
The full details of the original charge request. This stores any passed form details and can be useful if you need to later offer a recap of their original payment options as they were at the time of Charge creation.
meta Array
Any meta data values that were passed on the Charge. These will also be recorded on the Stripe charge object, and visible in the Stripe Dashboard.
notes String
Any admin added notes on the Charge. You can only add notes via the CP.
description String
An optional description string, as set at the time of charge creation.
dateCreated DateTime
The time the Charge was created.
status String
The status of the charge. Can be either live or test. A duplicate of the mode attribute, used for element filtering.
amount Number
The amount the Charge was for in decimals. ie. '5' for a $5 plan. If you want decimals included use the twig number_format filter.
amountInCents Number
The amount the Charge was for in pence/cents. ie. '500' for a $5 plan.
amountFormatted String
A nicely formatted version of the charge plan details. This will include the currency symbol. i.e. '$5.00' for a $5 plan
discountAmount Number
The amount of discount on the Charge in decimals. ie. '5' for a $5 plan. If you want decimals included use the twig number_format filter.
discountAmountFormatted String
A nicely formatted version of the discount applied to a charge plan details. This will include the currency symbol. i.e. '$5.00' for a $5 plan
hasDiscount Bool
If the charge has a discount applied.
shortname String
A useful helper to return a well formatted version of the plan name + value. The exact format of this will vary based on if the plan is recurring or one off. Will return similar to '$5.00', or '$5.00 Monthly', or '$5.00 Every 3 Months', etc.. Really just a shorthand wrapper for the amountFormatted and formatPlanName methods.
planInterval String, day, week, month, year or null
The recurring interval for the plan. Only used on recurring plans.
planIntervalCount Number
The number of interval periods this recurs under. ie. '1' means will recur every period, '3' means it'll recurring every third period. (ie. 3 weeks/months etc..)
currency String
The currency letter code for the plan. i.e. usd
[[ content ]] Mixed, field content.
In addition to all the default attributes and methods, you can attach your own custom fields to Charges. When you've attached a field you can access it like : {{ charge.someExampleField }} as you would on any other element model.
user UserModel
Used during guest registration. If you're registering a guest the user field will contain their user model as it was during the request. This is used to repopulate your user fields, and error messaging.
account Charge_AccountModel
The account the payment was sent to, as part of Connect. null if none.
applicationFeeInCents Number
The application fee collected as part of Connect.
applicationFeeFormatted String
The application fee formatted with a currency symbol, and decimals, ie; $9.35

Methods

In addition, the following methods accept optional arguments and can be used to tweak the display options.

formatPlanAmount( format ) 'symbol' or 'safe'
Returns a nicely formatted version of the charge plan amount. Passing 'symbol' is equivalent to the amountFormatted attribute, and returns similar to '$5.00'. Passing 'safe' returns the value with a currency letter code, similar to '5.00 USD'
formatDiscountAmount( format ) 'symbol' or 'safe'
Returns a nicely formatted version of the discount amount on a plan. Passing 'symbol' is equivalent to the amountFormatted attribute, and returns similar to '$5.00'. Passing 'safe' returns the value with a currency letter code, similar to '5.00 USD'
formatPlanName String
A nicely formatted version of the plan details, taking into account the recurring intervals. Will return similar to '$5.00', '$5.00 Monthly', '$5.00 Every 3 Months' etc..
isRecurring Bool
Returns true if the type for the charge is recurring, false otherwise.
isOneOff Bool
Returns true if the type for the charge is one-off, false otherwise.
getErrors( attribute )
Returns any errors for a specific attribute, used on the initial payment form. Pass an empty param to get all errors. You can see this in action on all the payment forms.