Charge Documentation

Documentation


Product Details Changelog FAQs

Hooks

If you need to extend Charge with extra validation, data handling or notification functions, you can use the built in hooks to trigger your own custom code. The available hooks are :

charge_pre_payment
Fired before a payment is attempted. Use for adding extra validation or forced values
charge_post_payment
Fired after a successful payment. Useful for extra notifications, or triggering other custom actions.
charge_create_member
Fired just after a new member is created, as part of the create_member function on the payment form.
charge_customer_created
Fired just after a new customer record is created on the Stripe api, as part of normal payments (both one-off and recurring)
charge_webhook_received_start Added in 1.8.2
Fired at the very start of the processing of an inbound Stripe webhook, before any of the standard handling runs
charge_action_start Added in 1.8.3
Fired when a user action starts, eg. the user is cancelling their subscription from the site, via the {exp:charge:act} tag.
charge_subscription_start_add_member Added in 1.8.5
Fired when a member is about to be added to a subscription.
charge_subscription_end_add_member Added in 1.8.5
Fired immediately after a member has been added to a subscription.
charge_subscription_start_remove_member Added in 1.8.5
Fired when a member is about to be removed from a subscription.
charge_subscription_end_remove_member Added in 1.8.5
Fired immediately after a member has been removed from a subscription.
charge_action_update_entry_start Added in 1.8.12
Fired just before an entry is updated from an action trigger
charge_action_update_entry_end Added in 1.8.12
Fired immediately after an entry has been created from an action trigger
charge_action_create_entry_start Added in 1.8.12
Fired just before an entry is created from an action trigger
charge_action_create_entry_end Added in 1.8.12
Fired immediately after an entry has been created from an action trigger

charge_pre_payment

The pre-payment hook can be used to add additional validation and data handling before a payment is taken. The hook is fired after basic validation has been performed, but before any errors are acted upon. At that point you can add your own errors, or remove any errors if needed. You can also update or alter the form data in the data array. The method is called passing a Charge object.

Hook Parameters

&$chargeObj ChargeModel
The full model of the charge about to be attempted. This includes all the various parts assembled from the inbound request and can be modified as needed. Returned object will be revalidated for saftey.

Example

If we wanted to add our own validation on a field 'meta:shipping_address1', we'd do something like this : 

public function charge_pre_payment(&$chargeObj)
{

    if(!isset($chargeObj->data['meta']['shipping_address1']) OR $chargeObj->data['meta']['shipping_address1'] == '') {
        $chargeObj->errors['meta:shipping_address1'] = 'Shipping Address is required';
    }

    //etc...

    return;
}

charge_post_payment

The post payment hook is triggered after a successful payment. You could use the post-payment hook to add your own special custom notifications, or to update another custom data table. You get the full data of both the customer, and the stripe data, exactly the same as recorded in the stripe payment table.

Hook Parameters

$type String 'recuring' or 'charge'
Denotes the type of payment that was just handled.
$hook_data Array
An array of all the payment data. This includes the Stripe response, so can be used to trigger extra events in your custom handling.

Note: The post-payment hook fires before any actions are triggered. If you need to you can alter details for any built in actions here, and they'll be acted on in any later triggered actions.

charge_create_member

The create member hook is triggered before payment is taken, immediately after a new member is created. It contains an array of the member details, and can be used to trigger extra details, or notifications as needed.

Hook Parameters

$data Array
An array of the data used to create the member. This follows the standard EE naming, and includes 'member_id', 'email', and any other details available during the member creation process. Only member fields are available here, the charge details are not included in the request.

charge_customer_created

The customer created hook is triggered after a customer record has been created on the Stripe api. The customer will have all their assigned details - including their payment method. This first just before the actual payment is taken.

The method calls with two parameters - the customer object as returned from stripe, and the current charge object, containing the details for the charge or subscription about to be created.

Hook Parameters

$customer Stripe_Customer
The Stripe customer object for the newly created customer. Details about specific values returned are available in the Stripe documenation on the Customer Object.

charge_webhook_received_start

The webhook received start hook is triggered when a Stripe webhook is received. This fires after basic validation has run to validate the event is real, but before any native Charge processing is triggered.

This method calls with 3 parameters - the event name, the mode, and the webhook event. Like :

Hook Parameters

$event_name String, eg: 'invoice.payment_received'
The triggering event name. A full list of possible Event Types, is available here.
$mode String, 'live' or 'test'
The mode for the event. Be sure to check this before performing critical logic.
$body Array
The full array of the webhook body. This will contain all the event details as we received them from Stripe.
charge_webhook_received_start($event_name, $mode, $body)
{
    if($event_name == 'invoice.payment_received' AND $mode == 'live') {
        // Invoice paid from a live transaction
        // etc..

        // Extract details as needed
        var_dump($body);
    }
}

charge_action_start

The hook is triggered at the very start of a user action processing. These are actions that you've exposed to your users via front-end forms, making use of the {exp:charge:act} tag to let them self-cancel, reactivate etc.. subscriptions.

This method calls with 4 parameters - the data for the action, the action name, the member id and any additional options passed. Like :

Hook Parameters

$data Array
An array of all the action data as it was triggered.
$action_name String. eg: 'end', 'reactivate'
The name for the action that was just triggered.
$member_id Integer, eg. '12'
The member_id for the triggering member.
$extra Array
An array of any extra details passed as part of the request. ie. $extra['at_period_end'] = true
public function charge_action_start($data, $action, $member_id, $extra)
{
    if($action == 'end') {
        // The user is ending their subscription

        if(isset($extra['at_period_end']) AND $extra['at_period_end'] == 'yes') {
            // Ending the subscription at the end of the paid period

        }
    }

    // etc...
}

Subscription Hooks

There are 4 hooks available to control member subscription events. All these hooks will only fire after full validation and safety checks have completed. ie. These hooks will only fire on valid events so you don't explictly need to revalidate within your extension.

Hook Parameters

$member_id Integer, eg. '12'
The member_id for this member
$group_id Integer, eg. '3'
The group_id the member is about to moved to. ie. the successful/failure group as appriopriate
$sub_data Array
An array of all the subscription member data. This array includes additional values for customer_id, charge_id and subscription_id. This can be very useful for later association to Stripe events.
$sub Array
An array of the subscription data. This array has the settings for the subscription - the success and failure member groups, email settings, and any other avaiable information.

You may also optionally set end_script = TRUE to stop any further execution after your hook returns.

charge_subscription_start_add_member

Fires immediately before a member is added to a subscription. At this point the member will have a valid account, but they haven't yet been moved to the subscription success group, and no emails have been sent or other records have been created.

If you have additional validation to perform (that could prevent a subscription from activating), set ee()->extensions->end_script = FALSE in your hook function. This will prevent any further actions triggering and the member will not be added to a subscription. Actual payments will be unaffected by this.

charge_subscription_end_add_member

Fires immediately after a member has been added to a subscription. At this point the member will have been moved to their new member group and their subscription record has been created. The actual welcome email is sent out via the webhook seperately.

charge_subscription_start_remove_member

Fires immediately before a member is removed from a subscription. At this point the member is still in the success member group, and everything is still active.

If you have additional validation to perform (that could stop a subscription ending), set ee()->extensions->end_script = FALSE in your hook function. This will prevent any further actions triggering and the member will not be added to a subscription. Actual payments will be unaffected by this.

charge_subscription_end_remove_member

Fires immediately after a member has been removed from a subscription. At this point the member will have been moved to their new member group and their subscription record has been updated. The actual goodbye email is sent out afterwards this function returns.

Example Usage for All Subscription Hooks

public function charge_subscription_start_add_member( $member_id, $group_id, $sub_data, $subscription )
{
    // Add extra validation.
    if( $this->_some_extra_validation($member_id) != TRUE )
    {
        // Stop this subscription from activating
        ee()->extensions->end_script = TRUE;
    }
}

public function charge_subscription_end_add_member( $member_id, $group_id, $sub_data, $subscription )
{
    // The member has been added to a subscription
    // Update an external api

    $this->_update_external_api('added', $member_id, $subscription);
}

public function charge_subscription_start_remove_member( $member_id, $group_id, $sub_data, $subscription )
{
    // Add extra validation.
    if( $this->_some_extra_validation($member_id) != TRUE )
    {
        // Keep this subscription active
        ee()->extensions->end_script = TRUE;
    }
}

public function charge_subscription_end_remove_member( $member_id, $group_id, $sub_data, $subscription )
{
    // The member has been removed to a subscription
    // Update an external api

    $this->_update_external_api('removed', $member_id, $subscription);
}

These examples are only the simplest possible setup. With the data available you could integrate Charge member subscriptions into a larger existing membership system.

charge_action_update_entry_start Added in 1.8.12

When an entry update action is triggered from a payment, this hook fires, just before the update process executes. You have the opportunity to alter the update values, add your own logic, or stop the action execution.

Hook Parameters

$entry_id Integer, eg. '12'
The entry_id of the entry about to be updated
$data Array
An array of the data that will be updated on the entry. Note - this array will be in the following format : $data = ['titles' => 'New Title Value', 'data' => ['field_id_10' => 'value', 'field_id_12' => 'othervalue']].
Only the values that are being updated will be populated, anything not included in the array will remain untouched during the update.
$charge_info Array
The array of the payment details that have triggered this action. Returns all the same variables as available in the charge:info tag

You can prevent the update of an entry by setting : 

ee()->extensions->end_script = TRUE;

Example Usage

If you want to alter the values - either to change the entry about to be updated by altering the entry_id, or the actual data to be updated, be sure to pass by reference on your hook usage method. 

public function charge_action_update_entry_start(&$entry_id, &$data) {
    // Alter the data array
    $data['data']['field_id_20'] = 'This is some default value set in our extension';

    return;
}

charge_action_update_entry_end Added in 1.8.12

Fired immediately after an entry has been updated via the triggered action.

You can use this hook if you need to perform some additional logic, update other related tables elsewhere, or apply your own logic for notifications and more.

Hook Parameters

$entry_id Integer, eg. '12'
The entry_id of the entry that was just updated
$data Array
An array of the data that was updated on the entry. Note - this will only contain the fields that were updated on the entry. Use the passed entry_id to pull the full entry details if required. The array will be in the following format : $data = ['titles' => 'New Title Value', 'data' => ['field_id_10' => 'value', 'field_id_12' => 'othervalue']].
$charge_info Array
The array of the payment details that have triggered this action. Returns all the same variables as available in the charge:info tag

charge_action_create_entry_start Added in 1.8.12

This hook is fired just before an entry is to be created from an action trigger.

This hook gives you the opportunity to alter the values of the entry about to be created, halt creation or add additional logic.

Hook Parameters

$channel_id Integer, eg. '2'
The id for the channel that's about to be used for creating the entry
$data Array
An array of the data to be used in the entry creation. The $data array will follow the standard format used in the channel_entries api. If you're altering the data passed, be sure to access the variables by reference
$charge_info Array
The array of the payment details that have triggered this action. Returns all the same variables as available in the charge:info tag

You can prevent the update of an entry by setting : 

ee()->extensions->end_script = TRUE;
public function charge_action_create_entry_start(&channel_id, &$data, $charge_info) {
    // Change the title
    $data['title'] = 'Purchase for '.$charge_info['amount_formatted'] .' by '.$charge_info['customer_name'];
    $data['author_id'] = 10; // Change the author_id

    return;
    }

charge_action_create_entry_end Added in 1.8.12

Fired immediately after an entry has been created from an action trigger.

This hook can be used to trigger extra actions, notifications, or custom logic. Be aware - the created entry is created via the native channel entries api, so the standard hooks related to entry creation will also have been triggered at this point. Depending on your requirements, those hooks might offer more options.

Hook Parameters

$entry_id Integer, eg. '12'
The entry_id for the just created entry.
$data Array
An array of the data to be used in the entry creation. The $data array will follow the standard format used in the channel_entries api. If you're altering the data passed, be sure to access the variables by reference
$charge_info Array
The array of the payment details that have triggered this action. Returns all the same variables as available in the charge:info tag

Contact support if you need any assistance with this or any other hooks.

Support

Having problems setting up and/or using Charge? 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.