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_startAdded 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_startAdded 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_memberAdded in 1.8.5- Fired when a member is about to be added to a subscription.
charge_subscription_end_add_memberAdded in 1.8.5- Fired immediately after a member has been added to a subscription.
charge_subscription_start_remove_memberAdded in 1.8.5- Fired when a member is about to be removed from a subscription.
charge_subscription_end_remove_memberAdded in 1.8.5- Fired immediately after a member has been removed from a subscription.
charge_action_update_entry_startAdded in 1.8.12- Fired just before an entry is updated from an action trigger
charge_action_update_entry_endAdded in 1.8.12- Fired immediately after an entry has been created from an action trigger
charge_action_create_entry_startAdded in 1.8.12- Fired just before an entry is created from an action trigger
charge_action_create_entry_endAdded 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
&$chargeObjChargeModel- 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
$typeString 'recuring' or 'charge'- Denotes the type of payment that was just handled.
$hook_dataArray- 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
$dataArray- 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
$customerStripe_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_nameString, eg: 'invoice.payment_received'- The triggering event name. A full list of possible Event Types, is available here.
$modeString, 'live' or 'test'- The mode for the event. Be sure to check this before performing critical logic.
$bodyArray- 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
$dataArray- An array of all the action data as it was triggered.
$action_nameString. eg: 'end', 'reactivate'- The name for the action that was just triggered.
$member_idInteger, eg. '12'- The member_id for the triggering member.
$extraArray- 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_idInteger, eg. '12'- The member_id for this member
$group_idInteger, eg. '3'- The group_id the member is about to moved to. ie. the successful/failure group as appriopriate
$sub_dataArray- 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.
$subArray- 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_idInteger, eg. '12'- The entry_id of the entry about to be updated
$dataArray- 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_infoArray- 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_idInteger, eg. '12'- The entry_id of the entry that was just updated
$dataArray- 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_infoArray- 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_idInteger, eg. '2'- The id for the channel that's about to be used for creating the entry
$dataArray- 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_infoArray- 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_idInteger, eg. '12'- The entry_id for the just created entry.
$dataArray- 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_infoArray- 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.
