Skip to content

Hooks and filters in Stripe

Like all Charitable extensions, Charitable Stripe is designed to be developer-friendly and includes hooks and filters that will help you make any customizations you need.

Paid Extension

Charitable Stripe is a premium plugin. Get it today with one of our plugin bundles.


Filters

charitable_stripe_statement_descriptor

Added in version 1.3.0

Filter the automatically formatted statement descriptor that is sent to Stripe.

Note: This filter is only used when the statement descriptor’s Format setting (under Charitable > Settings > Payment Gateways > Stripe) is set to “Use campaign title”.

Return Value

String. By default, this returns the first 22 characters of the campaign title.

Arguments

  • $descriptor (string)

    The default descriptor.

  • $donation (Charitable_Donation)

    The donation object.

  • $processor (Charitable_Donation_Processor)

    The donation processor object.

Usage

add_filter(
    'charitable_stripe_statement_descriptor',
    function( $descriptor, Charitable_Donation $donation ) {
        return 'My Custom Statement Descriptor';
    },
    10,
    2
);

charitable_stripe_metadata_fields

Added in version 1.4.0

Filter the list of Donation Fields which will be sent to Stripe as the metadata for a particular one-time or recurring donation.

Return Value

An array of keys for Donation Fields.

Arguments

  • $fields (array)

    The keys of all Donation Fields that will have their values sent to Stripe. By default, this will include any field which is shown in the front-end donation form, as well as donation_id and donor.

Usage

/**
 * Add a new field to the metadata.
 */
add_filter(
    'charitable_stripe_metadata_fields',
    function( $fields ) {
        // Add the name(s) of the campaign(s) receiving the donation to the metadata
        $fields[] = 'campaign_categories_list';
        return $fields;
    }
);

/**
 * Remove a field from the metadata.
 */
add_filter(
    'charitable_stripe_metadata_fields',
    function( $fields ) {
        unset( $fields['address'] );
        return $fields;
    }
);

charitable_stripe_charge_metadata

Added in version 1.3.0

Filter the metadata passed to a Payment Intent, Checkout Session, or Charge.

Return Value

An array of metadata as key=>value pairs.

Arguments

  • $metadata (array)

    The set of metadata.

  • $donation (Charitable_Donation)

    The donation object.

  • $processor (Charitable_Donation_Processor)

    The processor object.

charitable_stripe_webhook_events

Added in version 1.3.0

Filter the list of webhook events that Charitable is subscribed to receive notifications for from Stripe.

Return Value

An array of valid webhook event types.

Arguments

  • $events (array)

    The events that the webhook will be notified about.

  • $connect_application (boolean)

    Whether this is a webhook for a Connect application.

charitable_stripe_setup_webhooks

Added in version 1.3.0

Filter whether webhooks should be set up for this site.

By default, this will return true unless this is localhost.

Return Value

Boolean.

Arguments

  • $setup_webhooks (boolean)

    Whether the webhooks should be set up.

Usage

add_filter( 'charitable_stripe_setup_webhooks', '__return_false' );

charitable_stripe_default_event_processors

Added in version 1.3.0

Modify the default event processors for specific webhook event types.

Return Value

A key=>value array of Stripe event types and associated callback functions.

Arguments

  • $processors (array)

    Array of Stripe event types and associated callback functions.

charitable_stripe_languages_directory

Added in version 1.0.0

Modify the directory where extension translations are stored.

Return Value

A string representing the path to the languages directory, relative to the wp-content/plugins directory.

Arguments

  • $directory (string)

    The language directory path. Defaults to charitable-stripe/languages.

charitable_gateway_stripe_name

Added in version 1.0.0

Filter the gateway name as it is displayed in the admin area.

Return Value

String. Defaults to “Stripe”.

Arguments

  • $name (string)

    Gateway name.

charitable_stripe_theme_template_path

Added in version 1.4.0

Filter the Stripe theme template path.

Return Value

A string representing the directory where theme templates are stored, relative to the theme folder.

Arguments

  • $template_path (string)

    The template path. Defaults to charitable/charitable-stripe.

charitable_stripe_gateway_processor_checkout

Added in version 1.4.0

Filter the processor class used for handling Checkout donations.

Return Value

A string representing the name of a class that descends from the Charitable_Stripe_Gateway_Processor base class. Defaults to Charitable_Stripe_Gateway_Processor_Checkout.

Arguments

  • $class (string)

    The name of the Stripe gateway processor class.

  • $processor (Charitable_Donation_Processor)

    The Donation Processor helper.

charitable_stripe_gateway_processor_payment_intents

Added in version 1.4.0

Filter the processor used for handling PaymentIntent donations.

Return Value

A string representing the name of a class that descends from the Charitable_Stripe_Gateway_Processor base class. Defaults to Charitable_Stripe_Gateway_Processor_Payment_Intents.

Arguments

  • $class (string)

    The name of the Stripe gateway processor class.

  • $processor (Charitable_Donation_Processor )

    The Donation Processor helper.

charitable_stripe_customer_args

Added in version 1.2.2

Filter the Stripe customer arguments.

Return Value

An array of arguments which will be passed to a \Stripe\Customer::create() call.

Arguments

  • $args (array)

    The customer arguments.

  • $donor (Charitable_Donor)

    The Donor object.

charitable_stripe_session_args

Added in version 1.4.0

Filter the Session arguments.

Return Value

An array of arguments that will be used in a call to \Stripe\Checkout\Session::create().

Arguments

  • $args (array)

    The Session args.

  • $donation (Charitable_Donation)

    The donation object.

  • $processor (Charitable_Donation_Processor)

    The processor object.

  • $gateway (Charitable_Gateway_Stripe)

    The Stripe gateway class helper.

Usage

/**
 * Change the 'submit_type' argument to 'pay' instead of 'donate'.
 */
add_filter(
    'charitable_stripe_session_args',
    function( $args ) {
        if ( array_key_exists( 'submit_type', $args ) ) {
            $args['submit_type'] = 'pay';
        }
        return $args;
    }
);

charitable_stripe_payment_intent_args

Added in version 1.4.0

Filter the PaymentIntent arguments.

Return Value

An array of arguments which will be used in a \Stripe\PaymentIntent::create().

Arguments

  • $args (array)

    The PaymentIntent args.

  • $donation (Charitable_Donation)

    The donation object.

  • $processor (Charitable_Donation_Processor)

    The processor object.

  • $gateway (Charitable_Gateway_Stripe)

    The Stripe gateway class helper.

Usage

/**
 * Change the 'description' argument.
 */
add_filter(
    'charitable_stripe_payment_intent_args',
    function( $args, $donation ) {
        $args['description'] = 'My payment description';
        return $args;
    },
    10, 
    2
);

charitable_stripe_subscriptions_args

Added in version 1.4.0

Filter the arguments passed to Stripe to create a new Subscription.

Return Value

An array of arguments that are passed to a \Stripe\Subscription::create() call.

Arguments

  • $args (array)

    The subscription args.

  • $recurring (Charitable_Recurring_Donation)

    The recurring donation object.

  • $processor (Charitable_Stripe_Gateway_Processor)

    This gateway processor instance.

charitable_stripe_plan_args

Added in version 1.4.3

Filter the arguments passed to Stripe to make a new plan.

Return Value

An array of arguments that are passed to a \Stripe\Plan::create() call.

Arguments

  • $plan_args (array)

    The plan args to be sent to Stripe.

  • $plan (Charitable_Stripe_Plan)

    An instance of Charitable_Stripe_Plan object.

charitable_stripe_product_args

Added in version 1.4.3

Filter the arguments passed to Stripe to create a new product.

Return Value

An array of arguments that are passed to a \Stripe\Product::create() call.

Arguments

  • $product_args (array)

    The product arguments to be sent to Stripe.

  • $product (Charitable_Stripe_Product)

    An instance of Charitable_Stripe_Product.

charitable_stripe_product_statement_descriptor

Added in version 1.4.0

Filter the automatically formatted statement_descriptor for products.

Return Value

A string that will be used as the statement descriptor for a new Stripe Product object.

Arguments

  • $descriptor (string)

    The default descriptor.

  • $product (Charitable_Stripe_Product)

    The Charitable_Stripe_Product instance.

charitable_stripe_recurring_subscription_status

Added in version 1.2.0

Filter the status for a recurring subscription based on a Stripe status.

Return Value

String. A valid Charitable recurring donation status (one of charitable-pendingcharitable-activecharitable-onholdcharitable-cancelledcharitable-expiredcharitable-failedcharitable-cancel).

Arguments

  • $status (string)

    The Charitable status.

  • $stripe_status (string)

    Stripe’s status for the subscription. See Stripe’s list of possible statuses.

charitable_stripe_load_stripe_scripts_sitewide

Added in version 1.4.3

Whether to load the Stripe script site-wide.

Return Value

Boolean. Return true to load scripts site-wide (the default), or false to only load Stripe’s scripts on the donation form.

Arguments

  • $load (boolean)

    Whether to load the scripts site-wide. Defaults to true.

Usage

add_filter( 'charitable_stripe_load_stripe_scripts_sitewide', '__return_false' ); 

Action Hooks

charitable_stripe_ipn_event

Added in version 1.0.0

Fire an action hook to process the event.

Note that this will only fire for webhooks that have not already been processed by one of the default webhook handlers.

Return Value

Void

Arguments

  • $event_type (string)

    Type of event.

  • $event (\Stripe\Event)

    Stripe event object.