Registering a Payment Gateway

Ignition Crowdfunding ships with an Offline payment gateway. Add-on plugins (Stripe, PayPal, etc.) extend the same framework by registering their own gateway implementation, which appears in the Payments admin tab alongside Offline with the same listing UI, status badge, enable/disable toggle, and configuration sub-page.

This page walks through the four pieces you need to ship a gateway.

1. Subclass `Igcf_Payment_Gateway`

Implement the abstract methods. The class lives in includes/payment-gateways/class-igcf-payment-gateway.php.

<?php
class My_Stripe_Gateway extends Igcf_Payment_Gateway {

    public function get_id(): string {
        return 'stripe';
    }

    public function get_label(): string {
        return __( 'Stripe', 'my-igcf-stripe' );
    }

    public function get_description(): string {
        return __( 'Accept credit and debit cards via Stripe Checkout.', 'my-igcf-stripe' );
    }

    public function is_configured(): bool {
        $settings = get_option( 'my_igcf_stripe_settings', array() );
        return ! empty( $settings['publishable_key'] )
            && ! empty( $settings['secret_key'] );
    }

    public function register_settings_fields( string $page_slug ): void {
        add_settings_section(
            'my_igcf_stripe_keys',
            __( 'API Keys', 'my-igcf-stripe' ),
            '__return_false',
            $page_slug
        );

        add_settings_field(
            'publishable_key',
            __( 'Publishable Key', 'my-igcf-stripe' ),
            array( $this, 'render_publishable_field' ),
            $page_slug,
            'my_igcf_stripe_keys'
        );

        // ... register the rest, then call register_setting() once per option.
    }
}

Method	Purpose
`get_id()`	Unique gateway id. Used in URLs, settings keys, and as the value stored on each pledge’s `payment_method` column. Use your add-on’s prefix (e.g., `stripe`, `paypal`).
`get_label()`	Human-readable label shown in the Payments tab listing and on the configuration sub-page.
`get_description()`	Short one-line description below the label in the listing.
`is_configured()`	Return `true` when the gateway has every credential / setting it needs to accept a pledge. The Payments tab uses this to lock the Enabled checkbox and to drive the Not configured status badge.
`register_settings_fields( $page_slug )`	Called by Core when the gateway’s sub-page renders. Use the standard WordPress Settings API (`add_settings_section()`, `add_settings_field()`, `register_setting()`) targeted at the supplied `$page_slug`. Core renders the form wrapper and Save button.

The base class also offers render_checkout_field( $campaign_id, $amount_minor ) — a no-op by default. Override it to render gateway-specific UI on the checkout payment-method section (e.g., a Stripe Elements card form).

Two more optional overrides:

Method	Default	Override it when
`get_unavailable_reasons( $campaign_id )`	One `not_configured` reason when `is_configured()` is false, otherwise an empty array.	Your gateway can’t serve some campaigns, for example because the campaign’s creator hasn’t connected an account. Return every reason that applies, each an array of `code`, `message` (a plain translated sentence, escaped on output) and `fix_url` (an admin URL or `''`). An empty array means the gateway is offered. Administrators see the reasons in the Payment methods row of the campaign detail page. Override this, not `is_available_for_campaign()`: the default `is_available_for_campaign()` returns true exactly when this list is empty, so checkout and the explanation always agree.
`has_operator_settings()`	`false`	Your configuration screen registers a field whose key you’ve opened to operators through `igcf_operator_settings`. Returning `true` shows operators the Payments tab and an Edit Settings link to your screen. Leave it `false` for anything that touches credentials or where money is sent.

Other plugins can add reasons against your gateway through the igcf_gateway_unavailable_reasons filter.

2. Register the gateway on the action

Core fires igcf_register_payment_gateways on init priority 5 from Igcf_Payment_Gateway_Registry::register_core_gateways(). Hook the action and call the public helper:

add_action( 'igcf_register_payment_gateways', function () {
    igcf_register_payment_gateway( new My_Stripe_Gateway() );
} );

The helper delegates to the singleton registry. Registering the same id twice overwrites the earlier instance, matching the registry’s documented contract.

Once registered, the gateway:

appears in the Payments tab listing with its own row,
gets a configuration sub-page at ?page=igcf-settings&tab=payments&gateway={id} where its register_settings_fields() callback renders the form,
becomes selectable on the checkout via igcf_checkout_payment_method.

3. Claim the payment method on the checkout

When a backer submits the checkout, Core fires the igcf_checkout_payment_method filter in Igcf_Checkout::handle_post_submission() before creating the pledge. Add-ons return their gateway id to claim the request:

add_filter( 'igcf_checkout_payment_method', function ( $payment_method, $post, $campaign_id ) {
    if ( isset( $post['my_stripe_payment_intent'] ) ) {
        return 'stripe';
    }
    return $payment_method;
}, 10, 3 );

After this filter runs, Core arbitrates the returned value against the backer’s own submission, then validates it against the gateways available for the campaign:

A return that is not a registered gateway id is treated as “no opinion” — a misbehaving add-on rather than a claim — and is discarded in favour of the value the backer selected.
A registered id is a real claim. If it cannot serve this campaign (see campaign-aware availability), Core refuses the pledge: no pledge row is written, and the review step re-renders with a notice naming the unavailable gateway. Core never substitutes a different method, so your gateway is never silently swapped out — and no other gateway silently receives a pledge it did not claim.

When the winning method is available, Core writes a pledge with that payment_method value. The pledge starts in the pending status and moves to succeeded only when one of its payment attempts succeeds — for async gateways, when your webhook calls Igcf_Payment_Attempt_Service::transition_status( $attempt_id, 'succeeded', … ); for offline, when an administrator records the offline payment. See the Service Layer.

4. Hand off async-redirect flows

For gateways that bounce the backer to a hosted payment surface (Stripe Checkout, PayPal approval URL, etc.), hook igcf_checkout_after_pledge_create. It fires immediately after the pledge is created and just before Core’s default redirect to the in-site receipt:

add_action( 'igcf_checkout_after_pledge_create', function ( $pledge_id, $campaign_id, $payment_method ) {
    if ( 'stripe' !== $payment_method ) {
        return;
    }

    $session = create_stripe_checkout_session( $pledge_id, $campaign_id );

    // Persist the session id so the success handler can match the webhook back to the pledge.
    igcf_update_pledge_meta( $pledge_id, '_stripe_session_id', $session->id );

    wp_safe_redirect( $session->url );
    exit;
}, 10, 3 );

Notes:

The pledge is already persisted when this action fires. If you can’t continue (gateway API call fails, etc.), surface an error and either leave the pledge in the pending status for the admin to clean up or cancel it via Igcf_Pledge_Service::transition_status( $pledge_id, 'canceled', … ).
Pledges live in the wp_igcf_pledges custom table — use igcf_update_pledge_meta() from includes/igcf-pledge-helpers.php to write meta, not update_post_meta().
Calling exit after wp_safe_redirect() prevents Core’s default redirect from running.

Listing data for your gateway

The Payments tab listing’s Pledges column reads sitewide totals from Igcf_Pledge_Service::get_payment_method_stats(), which groups by the payment_method column on wp_igcf_pledges. Pledges your gateway writes will appear automatically as soon as they exist.

Reacting to enable/disable

Core fires igcf_payment_gateway_state_changed after every successful write through Igcf_Payment_Gateway_Service::set_enabled(). Listen if your add-on caches state or schedules companion work:

add_action( 'igcf_payment_gateway_state_changed', function ( $gateway_id, $enabled ) {
    if ( 'stripe' === $gateway_id && ! $enabled ) {
        wp_clear_scheduled_hook( 'my_stripe_nightly_reconciliation' );
    }
}, 10, 2 );

Igcf_Payment_Gateway_Service — read/write API for the enabled state with built-in guards.
igcf/set-payment-gateway-enabled ability — the REST surface the Payments tab uses to flip the toggle.
Payments admin tab — administrator-facing view of every registered gateway.