suredonation_integration_payload Filter Hook

Overview

The suredonation_integration_payload filter allows developers to modify the donation data sent to SureDonation integrations and third-party listeners.

It provides a shared, integration-safe representation of a donation that is used by OttoKit, SureDonation action hooks, and other integration listeners.

Use this filter when you need to remove, modify, or sanitize donation data before it is passed to integrations.

When to Use This Filter

Use this filter when you need to:

• Modify donation data sent to integrations.
• Remove sensitive donor information.
• Customize the data available to automation workflows.
• Apply privacy rules to donation data.
• Mask donor information for anonymous donations.
• Remove specific fields from the integration payload.

Anonymous Donations

The integration payload contains the donor’s actual identity even when a donation is marked as anonymous.

The is_anonymous setting controls how the donor is represented in public donor lists. It does not automatically remove the donor’s identity from integration payloads.

This allows automation workflows to use the is_anonymous field to decide how donor information should be handled.

If your site’s privacy policy requires anonymous donor information to be removed before it reaches integrations, use this filter to modify the payload.

Filter Signature

apply_filters( 'suredonation_integration_payload',   $payload,   $donation);

apply_filters( 'suredonation_integration_payload',   $payload,   $donation);

Parameters

Payload Data

The payload can contain donation, payment, subscription, and donor information, including:

• amount
• currency
• gateway
• payment_status
• payment_mode
• donation_type
• transaction_id
• subscription_id
• subscription_status
• donor_comment
• is_anonymous
• created_at
• updated_at
• Donor identity fields

Return Value

Return the modified $payload array.

return $payload;

You can also remove individual keys from the payload.

unset( $payload[‘donor_phone’] );

return $payload;

Removing a field means that field will no longer be available to integration listeners that receive the filtered payload.

Basic Usage

add_filter('suredonation_integration_payload',  'your_custom_function',  10,  2);

function your_custom_function( $payload, $donation ) {

    // Your custom logic here.

    return $payload;

}

add_filter('suredonation_integration_payload',  'your_custom_function',  10,  2);

function your_custom_function( $payload, $donation ) {

    // Your custom logic here.

    return $payload;

}

Example: Mask Anonymous Donors

The following example replaces donor identity information with anonymous values when the donation is marked as anonymous.

add_filter( 'suredonation_integration_payload', 'mysite_mask_anonymous_donors', 10, 2);

function mysite_mask_anonymous_donors( $payload, $donation ) {

    if ( empty( $payload['is_anonymous'] ) ) {

        return $payload;

    }

    // Remove donor identity before the payload reaches integrations.

    $payload['donor_name']  = 'Anonymous';

    $payload['donor_email'] = '';

    $payload['donor_phone'] = '';

    return $payload;

}

add_filter( 'suredonation_integration_payload', 'mysite_mask_anonymous_donors', 10, 2);

function mysite_mask_anonymous_donors( $payload, $donation ) {

    if ( empty( $payload['is_anonymous'] ) ) {

        return $payload;

    }

    // Remove donor identity before the payload reaches integrations.

    $payload['donor_name']  = 'Anonymous';

    $payload['donor_email'] = '';

    $payload['donor_phone'] = '';

    return $payload;

}

How the Example Works

1. The filter receives the curated donation payload.
2. It checks the is_anonymous value.
3. If the donation is not anonymous, the original payload is returned.
4. If the donation is anonymous, donor identity fields are modified.
5. The modified payload is passed to all integration listeners.

Example: Remove a Field

You can remove a field completely when it should not be shared with integrations.

add_filter( 'suredonation_integration_payload', 'mysite_remove_donor_phone',  10,  2);

function mysite_remove_donor_phone( $payload, $donation ) {

    unset( $payload['donor_phone'] );

    return $payload;

}

add_filter( 'suredonation_integration_payload', 'mysite_remove_donor_phone',  10,  2);

function mysite_remove_donor_phone( $payload, $donation ) {

    unset( $payload['donor_phone'] );

    return $payload;

}

After this filter runs, donor_phone will not be available in the integration payload.

Integration Flow

The filter is part of the shared integration payload process:

1. SureDonation receives or creates donation data.
2. SureDonation builds the curated integration payload.
3. The suredonation_integration_payload filter is applied.
4. Your callback can modify or remove fields.
5. The filtered payload is passed to integration listeners.
6. OttoKit and SureDonation donation action hooks receive the resulting payload.

Because this is a shared payload builder, a change made through this filter affects all integrations that use the resulting payload.

Performance Considerations

This filter can run for every integration dispatch.

Keep your callback:

• Lightweight.
• Fast.
• Side-effect free.

Avoid performing expensive database queries, external API requests, or other heavy operations inside this filter.

If you need to perform an action when a donation is created, completed, or refunded, use the appropriate action hook instead.

Filter vs Action Hook

Use suredonation_integration_payload when you need to modify the data sent to integrations.

Use an action hook when you need to perform an operation after a donation event occurs.

For example:

add_action( 'suredonation_donation_completed', 'mysite_process_completed_donation',  10,  1);

add_action( 'suredonation_donation_completed', 'mysite_process_completed_donation',  10,  1);

This is preferable to performing side effects inside the integration payload filter.

Related Hooks

• suredonation_donation_created: Runs when a donation is created.
• suredonation_donation_completed: Runs when a donation is completed.
• suredonation_donation_refunded: Runs when a donation is refunded.
• suredonation_suretriggers_integration_data_filter: Filters the configuration payload used by the OttoKit integration.