Our EE Addons have Moved!
Our ExpressionEngine Add-ons have been acquired by EE Harbor. Head over there for documentation, info and support.
Our ExpressionEngine Add-ons have been acquired by EE Harbor. Head over there for documentation, info and support.
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
charge_post_payment
charge_create_member
charge_customer_created
charge_webhook_received_start
Added in 1.8.2charge_action_start
Added in 1.8.3charge_subscription_start_add_member
Added in 1.8.5charge_subscription_end_add_member
Added in 1.8.5charge_subscription_start_remove_member
Added in 1.8.5charge_subscription_end_remove_member
Added in 1.8.5charge_action_update_entry_start
Added in 1.8.12charge_action_update_entry_end
Added in 1.8.12charge_action_create_entry_start
Added in 1.8.12charge_action_create_entry_end
Added in 1.8.12The 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.
&$chargeObj
ChargeModelIf 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; }
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.
$type
String 'recuring' or 'charge'$hook_data
ArrayNote: 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.
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.
$data
ArrayThe 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.
$customer
Stripe_CustomerThe 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 :
$event_name
String, eg: 'invoice.payment_received'$mode
String, 'live' or 'test'$body
Arraycharge_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); } }
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 :
$data
Array$action_name
String. eg: 'end', 'reactivate'$member_id
Integer, eg. '12'$extra
Array$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... }
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.
$member_id
Integer, eg. '12'$group_id
Integer, eg. '3'$sub_data
Array$sub
ArrayYou may also optionally set end_script = TRUE
to stop any further execution after your hook returns.
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.
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.
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.
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.
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.
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.
$entry_id
Integer, eg. '12'$data
Array$data = ['titles' => 'New Title Value', 'data' => ['field_id_10' => 'value', 'field_id_12' => 'othervalue']]
. $charge_info
ArrayYou can prevent the update of an entry by setting :
ee()->extensions->end_script = TRUE;
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; }
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.
$entry_id
Integer, eg. '12'$data
Array$data = ['titles' => 'New Title Value', 'data' => ['field_id_10' => 'value', 'field_id_12' => 'othervalue']]
.$charge_info
ArrayThis 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.
$channel_id
Integer, eg. '2'$data
Array$charge_info
ArrayYou 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; }
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.
$entry_id
Integer, eg. '12'$data
Array$charge_info
ArrayContact support if you need any assistance with this or any other hooks.