[Donor submits form]
        │
        ▼
① giftflow_donation_form_fields          ← filter: modify/add form fields
② giftflow_donation_form_before_process_donation  ← action: validate (recaptcha)
        │
        ▼
③ giftflow_donation_validate             ← filter: custom validation logic
④ giftflow_donation_before_create        ← filter + action: intercept before DB insert
⑤ giftflow_donation_post_data            ← filter: modify WP post args
⑥ giftflow_donation_created              ← action: donation post created (status = pending)
⑦ giftflow_donation_meta_saved           ← action: all meta saved
        │
        ▼
⑧ [gateway::process_payment()]           ← each gateway runs its own logic
        │
        ├── giftflow_stripe_prepare_payment_intent_data  ← Stripe filter
        ├── giftflow_stripe_customer_data                ← Stripe filter
        ├── giftflow_paypal_prepare_payment_data         ← PayPal filter
        │
        ▼
⑨ giftflow_donation_before_status_update ← action: fires before status changes
⑩ giftflow_donation_status_updated       ← action: status changed
⑪ giftflow_donation_status_{$status}     ← dynamic action: e.g. _completed, _failed
        │
        ▼
⑫ giftflow_donation_after_payment_processed  ← action: emails, user creation

Type:       filter
Parameters: array $fields — sanitized form fields
Returns:    array
Source:     class-forms.php

add_filter( 'giftflow_donation_form_fields', function( $fields ) {
    // Example: parse a hidden field your template added
    $fields['my_custom_field'] = sanitize_text_field( $fields['my_custom_field'] ?? '' );
    return $fields;
} );

Type:       action
Parameters: array $fields — sanitized form fields
Priority:   10 (reCAPTCHA), add yours at higher priority
Source:     class-forms.php

add_action( 'giftflow_donation_form_before_process_donation', function( $fields ) {
    $min = 5.00;
    if ( floatval( $fields['donation_amount'] ) < $min ) {
        wp_send_json_error( array( 'message' => 'Minimum donation is $5.' ) );
    }
}, 20 );

Type:       filter
Parameters: true|WP_Error $valid, array $data
Returns:    true|WP_Error
Source:     class-donations.php :: validate_donation_data()

add_filter( 'giftflow_donation_validate', function( $valid, $data ) {
    if ( empty( $data['campaign_id'] ) ) {
        return new WP_Error( 'no_campaign', 'A campaign must be selected.' );
    }
    return $valid;
}, 10, 2 );

filter parameters: array $data
filter returns:    array (modified data)

action parameters: array $data
Source: class-donations.php :: create()

// Filter — modify data
add_filter( 'giftflow_donation_before_create', function( $data ) {
    $data['donor_name'] = ucwords( strtolower( $data['donor_name'] ) );
    return $data;
} );
 
// Action — log or notify
add_action( 'giftflow_donation_before_create', function( $data ) {
    // fire-and-forget logging, not modifying data
    error_log( 'Creating donation for: ' . $data['donor_email'] );
} );

Type:       filter
Parameters: array $post_data, array $data
Returns:    array
Source:     class-donations.php :: create()

add_filter( 'giftflow_donation_post_data', function( $post_data, $data ) {
    $post_data['post_title'] = 'Donation — ' . gmdate( 'Y-m-d H:i' );
    return $post_data;
}, 10, 2 );

Type:       action
Parameters: WP_Error $error, array $data
Source:     class-donations.php :: create()

add_action( 'giftflow_donation_create_failed', function( $error, $data ) {
    // Alert admin
    wp_mail( get_option('admin_email'), 'Donation creation failed', $error->get_error_message() );
}, 10, 2 );

Type:       action
Parameters: int $donation_id, array $data
Source:     class-donations.php :: create()

add_action( 'giftflow_donation_created', function( $donation_id, $data ) {
    // Donation row exists in DB. Payment not yet processed.
    update_post_meta( $donation_id, '_my_custom_meta', 'value' );
}, 10, 2 );

Type:       action
Parameters: int $donation_id, array $data
Source:     class-donations.php :: save_donation_meta()

add_action( 'giftflow_donation_meta_saved', function( $donation_id, $data ) {
    if ( ! empty( $data['my_custom_field'] ) ) {
        update_post_meta( $donation_id, '_my_custom_field', sanitize_text_field( $data['my_custom_field'] ) );
    }
}, 10, 2 );

Type:       action
Parameters: none
Source:     class-gateway-base.php :: init_gateways()

add_action( 'giftflow_register_gateways', function() {
    new My_Custom_Gateway();
} );

Type:       action
Parameters: array $gateway_registry — [ id => Gateway_Base instance, ... ]
Source:     class-gateway-base.php :: init_gateways()

add_action( 'giftflow_gateways_initialized', function( $registry ) {
    // All gateways are now registered and sorted
    foreach ( $registry as $id => $gateway ) {
        if ( $gateway->is_enabled() ) {
            // do something per enabled gateway
        }
    }
} );

Type:       action
Parameters: string $gateway_id, Gateway_Base $gateway_instance
Source:     class-gateway-base.php :: register_gateway()

add_action( 'giftflow_gateway_registered', function( $id, $gateway ) {
    if ( 'stripe' === $id ) {
        // custom Stripe initialization
    }
}, 10, 2 );

Type:       action
Parameters: Gateway_Base $gateway_instance
Source:     class-gateway-base.php :: init_hooks()

add_action( 'giftflow_gateway_init_hooks', function( $gateway ) {
    if ( $gateway->get_id() === 'stripe' ) {
        // add extra Stripe-specific hooks
    }
} );

Type:       filter
Parameters: array $gateways — keyed by gateway ID
Returns:    array
Source:     class-gateway-base.php :: init_hooks()

// Remove a gateway from the donation form
add_filter( 'giftflow_payment_gateways', function( $gateways ) {
    unset( $gateways['direct_bank_transfer'] );
    return $gateways;
} );

Type:       filter (hooked as action with return)
Parameters: array $payment_fields
Returns:    array
Source:     class-gateway-base.php :: init_hooks()

add_filter( 'giftflow_payment_methods_settings', function( $fields ) {
    // Add a custom global payment setting
    $fields['my_setting'] = array(
        'id'    => 'giftflow_my_setting',
        'name'  => 'giftflow_payment_options[my_setting]',
        'type'  => 'textfield',
        'label' => __( 'My Setting', 'my-plugin' ),
    );
    return $fields;
} );

Type:       filter
Parameters: array $payment_intent_data, array $form_data, int $donation_id
Returns:    array
Source:     class-stripe.php :: prepare_payment_intent_data()

add_filter( 'giftflow_stripe_prepare_payment_intent_data', function( $intent_data, $form_data, $donation_id ) {
    $intent_data['statement_descriptor'] = 'CHARITY ORG';
    $intent_data['metadata']['custom_key'] = 'custom_value';
    return $intent_data;
}, 10, 3 );

Type:       filter
Parameters: array $customer_data, array $form_data, int $donation_id
Returns:    array
Source:     class-stripe.php :: get_or_create_stripe_customer()

add_filter( 'giftflow_stripe_customer_data', function( $customer_data, $form_data, $donation_id ) {
    $customer_data['metadata']['site_id'] = get_current_blog_id();
    return $customer_data;
}, 10, 3 );

Type:       filter
Parameters: string $currency — default 'USD'
Returns:    string
Source:     class-stripe.php :: get_currency()

add_filter( 'giftflow_stripe_currency', function( $currency ) {
    return 'EUR';
} );

Type:       filter
Parameters: string $country — default 'US'
Returns:    string
Source:     class-stripe.php :: get_country_code()

add_filter( 'giftflow_stripe_country_code', fn() => 'DE' );

Type:       filter
Parameters: array $supports, Stripe_Gateway $gateway
Returns:    array
Source:     class-stripe.php :: init_gateway()

add_filter( 'giftflow_stripe_gateway_supports', function( $supports ) {
    $supports[] = 'recurring';
    return $supports;
}, 10, 2 );

Type:       action
Parameters: int $donation_id, string $transaction_id, array $payment_intent_data
Source:     class-stripe.php :: handle_successful_payment_intent()

add_action( 'giftflow_stripe_payment_completed', function( $donation_id, $transaction_id, $intent_data ) {
    // Send custom receipt, update CRM, etc.
}, 10, 3 );

Type:       action
Parameters: int $donation_id, string $subscription_id, array $subscription_data
Source:     class-stripe.php :: process_recurring_payment()

add_action( 'giftflow_stripe_subscription_created', function( $donation_id, $sub_id, $sub_data ) {
    // Store sub_id in your own table, notify admin, etc.
}, 10, 3 );

Type:       action
Parameters: int $renewal_id, int $parent_donation_id, string $subscription_id, array $invoice_data
Source:     class-stripe.php :: handle_invoice_paid()

add_action( 'giftflow_stripe_recurring_renewal_created', function( $renewal_id, $parent_id, $sub_id, $invoice ) {
    // e.g. sync to external fundraising platform
}, 10, 4 );

// Example — send a refund receipt on charge.refunded
add_action( 'giftflow_stripe_webhook_charge_refunded', function( $donation_id, $charge ) {
    $donation = giftflow_get_donation_data_by_id( $donation_id );
    wp_mail( $donation->donor_email, 'Your refund has been processed', '...' );
}, 10, 2 );
 
// Example — handle subscription cancellation
add_action( 'giftflow_stripe_subscription_cancelled', function( $donation_id, $sub_id, $sub ) {
    update_post_meta( $donation_id, '_recurring_status', 'cancelled' );
    do_action( 'giftflow_donation_after_payment_processed', $donation_id, false );
}, 10, 3 );

Type:       filter
Parameters: array $supports, PayPal_Gateway $gateway
Returns:    array
Source:     class-paypal.php :: init_gateway()

Type:       filter
Parameters: array $paypal_data, array $form_data, int $donation_id
Returns:    array
Source:     class-paypal.php :: prepare_payment_data()

add_filter( 'giftflow_paypal_prepare_payment_data', function( $data, $form_data, $donation_id ) {
    $data['metadata']['source'] = 'landing_page_campaign';
    return $data;
}, 10, 3 );

Type:       action
Parameters: int $donation_id, string $transaction_id, array $response_data
Source:     class-paypal.php :: capture_paypal_order(), handle_successful_payment()

add_action( 'giftflow_paypal_payment_completed', function( $donation_id, $transaction_id, $data ) {
    // Log or sync with external system
}, 10, 3 );

add_action( 'giftflow_paypal_webhook_payment_completed', function( $donation_id, $resource ) {
    // Extra handling for PayPal webhook confirmation
}, 10, 2 );

Type:       action
Parameters: int $donation_id, string $new_status, string $old_status
Source:     class-donations.php :: update_status()

add_action( 'giftflow_donation_before_status_update', function( $donation_id, $new_status, $old_status ) {
    // Log the incoming transition
    error_log( "Donation #{$donation_id}: {$old_status} → {$new_status}" );
}, 10, 3 );

Type:       action
Parameters: int $donation_id, string $new_status, string $old_status
Source:     class-donations.php :: update_status()

add_action( 'giftflow_donation_status_updated', function( $donation_id, $new_status, $old_status ) {
    if ( 'completed' === $new_status && 'pending' === $old_status ) {
        // Trigger a campaign milestone check
    }
}, 10, 3 );

Type:       action (dynamic)
Parameters: int $donation_id, string $old_status
Source:     class-donations.php :: update_status()

// React when a donation completes
add_action( 'giftflow_donation_status_completed', function( $donation_id, $old_status ) {
    // Send custom thank-you SMS, update leaderboard, etc.
}, 10, 2 );
 
// React when a donation is refunded
add_action( 'giftflow_donation_status_refunded', function( $donation_id, $old_status ) {
    // Adjust campaign totals or notify the team
}, 10, 2 );

Type:       filter
Parameters: array $statuses — default: ['pending','completed','failed','refunded','cancelled']
Returns:    array
Source:     class-donations.php :: get_valid_statuses()

add_filter( 'giftflow_donation_valid_statuses', function( $statuses ) {
    $statuses[] = 'on_hold';
    return $statuses;
} );

Type:       action
Parameters: int $donation_id, mixed $payment_result
Source:     class-forms.php :: process_donation()
            class-paypal.php :: capture_paypal_order() (also fires manually)

// Add your own post-payment logic
add_action( 'giftflow_donation_after_payment_processed', function( $donation_id, $payment_result ) {
    if ( $payment_result !== true ) {
        return; // Skip if not a direct success
    }
 
    $donation = giftflow_get_donation_data_by_id( $donation_id );
 
    // Example: sync to a CRM
    my_crm_sync( array(
        'email'    => $donation->donor_email,
        'amount'   => $donation->amount,
        'campaign' => $donation->campaign_name,
    ) );
}, 20, 2 );

// Modify all data passed to the admin email template
add_filter( 'giftflow_new_donation_admin_email_args', function( $args, $donation_id, $donation_data ) {
    $args['custom_note'] = 'Processed via mobile app';
    return $args;
}, 10, 3 );
 
// Modify admin email subject line
add_filter( 'giftflow_new_donation_admin_email_subject', function( $subject, $donation_id, $donation_data ) {
    return '[URGENT] ' . $subject;
}, 10, 3 );
 
// Modify admin email header text
add_filter( 'giftflow_new_donation_admin_email_header', function( $header, $donation_id, $donation_data ) {
    return '🎉 New Donation Received';
}, 10, 3 );

// Modify all data passed to the donor thank-you template
add_filter( 'giftflow_thanks_donor_email_args', function( $args, $donation_id, $donation_data ) {
    $args['custom_message'] = 'Your receipt number is ' . $donation_id;
    return $args;
}, 10, 3 );
 
// Modify donor email subject
add_filter( 'giftflow_thanks_donor_email_subject', function( $subject, $donation_id, $donation_data ) {
    return $subject . ' 🙏';
}, 10, 3 );
 
// Modify donor email header
add_filter( 'giftflow_thanks_donor_email_header', function( $header, $donation_id, $donation_data ) {
    return 'Thank you for making a difference!';
}, 10, 3 );

Type:       action
Parameters: int $donation_id, string $reference_number, array $data
Source:     class-direct-bank-transfer.php :: process_payment()

add_action( 'giftflow_bank_transfer_payment_pending', function( $donation_id, $ref_number, $data ) {
    // Email admin with reference number for manual matching
    $msg = "New bank transfer pending.\nRef: {$ref_number}\nDonation: #{$donation_id}";
    wp_mail( get_option('admin_email'), 'Bank Transfer Pending', $msg );
}, 10, 3 );