Skip to main content

WordPress hooks for Stitch Payments

All Stitch-specific filters use the stitch_payments_* prefix unless noted. Most filters receive the Gateway instance as the last parameter — remember to pass the argument count to add_filter() when you use it (for example add_filter( '...', $callback, 10, 2 )).

Code snippets below belong in a small site plugin or your theme's functions.php.

:::note Renamed in 0.8.0 Before 0.8.0 these hooks were named woocommerce_stitch_*. The woocommerce_ prefix belongs to WooCommerce, so every Stitch hook is now stitch_payments_*. Callbacks still registered on an old name keep working: the plugin runs them first and logs a deprecation notice (_deprecated_hook) that names the new hook. Rename them when convenient — the old names will be removed in a future release. :::

Quick index​

HookTypeUse it to…
stitch_payments_payment_form_template_argsFilterChange anything passed to the classic payment form template
stitch_payments_checkout_field_labelsFilterRename the card fields
stitch_payments_checkout_display_settingsFilterOverride branding (logo, icons, description) in code
stitch_payments_payment_form_i18nFilterReword any UI or validation message
stitch_payments_saved_payment_methodsFilterHide or reorder saved cards at checkout
stitch_payments_accepted_card_brandsFilterChange which brand icons appear in the header
stitch_payments_payment_header_htmlFilterRewrite the rendered header HTML
stitch_payments_style_presetsFilterRegister your own checkout style preset
stitch_payments_iframe_cssFilterRestyle the card-number field inside the CardPointe iframe
stitch_payments_customer_decline_messageFilterCustomize decline messages shown to customers
stitch_payments_gateway_script_paramsFilterAdjust data passed to the classic checkout script
stitch_payments_blocks_payment_method_dataFilterAdjust data passed to the Blocks checkout script
stitch_payments_is_checkout_contextFilterTeach the plugin about custom checkout pages
stitch_payments_should_enqueue_payment_assetsFilterForce or block CSS/JS loading
stitch_payments_hide_native_saved_methodsFilterRestore WooCommerce's native saved-card options
stitch_payments_register_gatewayFilterConditionally disable the gateway
stitch_payments_allowed_api_hostsFilterAllow a white-label CardPointe API host
stitch_payments_max_charge_amountFilterChange the largest single charge the gateway will send
stitch_payments_surcharge_rate_limitFilterChange how many card fee checks one shopper can make
stitch_payments_surcharge_unconfirmed_alert_thresholdFilterChange when the admin is warned about unconfirmed card fees
stitch_payments_debug_logFilterTurn full API logging on or off in code
stitch_payments_ach_authorization_textFilterReword the bank debit authorization
stitch_payments_before_payment_form and friendsActionPrint custom content around the classic form
stitch_payments_loadedActionRun code once the plugin has booted
stitch_payments_surcharge_unconfirmedActionReact to an order paid without a confirmed card fee
stitch_payments_ach_payment_returnedActionReact to a bank payment the bank returned after it cleared
stitch_payments_saved_card_closedActionReact before a closed saved card is removed

Filters​

stitch_payments_payment_form_template_args​

Filter every variable passed to the classic payment-form.php template — the broadest hook for the classic form.

Parameters: $args (array), $gateway (Gateway)

$args keys: gateway, enable_profiles, checkout_display, field_labels, i18n, saved_methods, default_acct_id

// Change the "save card" checkbox text and disable saved cards for one
// product page's express flow.
add_filter( 'stitch_payments_payment_form_template_args', function ( $args, $gateway ) {
$args['i18n']['save_card'] = 'Store this card securely for next time';

if ( is_page( 'express-checkout' ) ) {
$args['enable_profiles'] = false;
$args['saved_methods'] = array();
}

return $args;
}, 10, 2 );

stitch_payments_checkout_field_labels​

Rename the four card fields. Applies to classic checkout, Blocks checkout, and the JS validation messages that reference them. (Merchants can also change these in gateway settings without code.)

Parameters: $labels (array), $gateway (Gateway)

$labels keys: card_number, expiry, cvv, cardholder_name

add_filter( 'stitch_payments_checkout_field_labels', function ( $labels, $gateway ) {
$labels['card_number'] = 'Card #';
$labels['cvv'] = 'Security code';
$labels['cardholder_name'] = 'Name as shown on card';
return $labels;
}, 10, 2 );

stitch_payments_checkout_display_settings​

Override the branding options in code — useful when the setting should depend on context rather than a fixed admin choice.

Parameters: $settings (array), $gateway (Gateway)

$settings keys: show_logo (bool), show_card_icons (bool), show_description (bool), description (string), logo_url (string)

// Use a seasonal logo in December and always hide the description.
add_filter( 'stitch_payments_checkout_display_settings', function ( $settings, $gateway ) {
if ( '12' === gmdate( 'm' ) ) {
$settings['logo_url'] = 'https://example.com/img/logo-holiday.png';
}

$settings['show_description'] = false;
return $settings;
}, 10, 2 );

stitch_payments_payment_form_i18n​

Reword any string the payment form shows — headings, buttons, surcharge notices, and every validation message. Works for classic checkout, Blocks checkout, and the shared JS.

Parameters: $strings (array), $gateway (Gateway)

Commonly changed keys: payment_header, accepted_cards, use_new_card, save_card, surcharge_notice, checkout_surcharge_disclosure, calculating, no_surcharge, card_number_invalid, fix_errors_title (about 30 keys total — inspect the array to see them all)

add_filter( 'stitch_payments_payment_form_i18n', function ( $strings, $gateway ) {
$strings['payment_header'] = 'Pay securely by card';
$strings['save_card'] = 'Remember this card';
// %s is replaced with the formatted fee amount.
$strings['surcharge_notice'] = 'This card carries a %s processing fee.';
return $strings;
}, 10, 2 );

stitch_payments_saved_payment_methods​

Filter the saved cards offered at checkout (classic and Blocks). The array is keyed by CardPointe account ID.

Parameters: $methods (array), $gateway (Gateway)

Each entry: profile_id, acct_id, last_four, card_type, expiry (MM/YY), default (bool)

// Hide saved cards that have already expired.
add_filter( 'stitch_payments_saved_payment_methods', function ( $methods, $gateway ) {
$cutoff = gmdate( 'ym' ); // Current year+month as YYMM.

foreach ( $methods as $acct_id => $method ) {
$digits = preg_replace( '/\D/', '', (string) $method['expiry'] ); // MM/YY -> MMYY.

if ( 4 === strlen( $digits ) && substr( $digits, 2 ) . substr( $digits, 0, 2 ) < $cutoff ) {
unset( $methods[ $acct_id ] );
}
}

return $methods;
}, 10, 2 );

stitch_payments_accepted_card_brands​

Change which brand icons render in the payment header. Default: visa, mastercard, amex, discover.

Parameters: $accepted (array of brand slugs), $args (array of header template args)

// Don't advertise Amex.
add_filter( 'stitch_payments_accepted_card_brands', function ( $accepted ) {
return array_diff( $accepted, array( 'amex' ) );
} );
note

This only changes the icons shown; it does not block a card brand from being processed. Card acceptance is controlled by your CardPointe merchant account.

stitch_payments_payment_header_html​

Filter the final rendered header (logo, icons, description) as HTML. Output is sanitized afterwards with Card_Icons::kses_payment_header_html(), so scripts and unexpected tags are stripped.

Parameters: $html (string), $args (array of header template args)

// Append a trust message below the header.
add_filter( 'stitch_payments_payment_header_html', function ( $html, $args ) {
return $html . '<p class="stitch-trust-note">PCI-compliant &middot; your card number never touches our servers.</p>';
}, 10, 2 );

stitch_payments_style_presets​

Since 0.4.0. Register or modify the presets offered by the Checkout style setting (WooCommerce → Settings → Payments → Stitch). Each preset has a translated label and a tokens map of --stitch-* CSS variables; tokens you omit keep their defaults. Built-in presets: default, minimal, compact, dark.

Parameters: $presets (array keyed by preset slug)

// Add a "Brand" preset merchants can pick in gateway settings.
add_filter( 'stitch_payments_style_presets', function ( $presets ) {
$presets['brand'] = array(
'label' => __( 'Brand', 'my-theme' ),
'tokens' => array(
'--stitch-accent' => '#ff6600', // Orange focus/selection.
'--stitch-accent-soft' => '#fff3eb', // Selected saved-card background.
'--stitch-focus-ring' => 'rgba(255, 102, 0, 0.18)', // Glow on the focused field.
'--stitch-header-bg' => 'linear-gradient(135deg, #fff7f0, #ffe9d6)',
'--stitch-radius-sm' => '4px', // Squarer inputs.
'--stitch-field-height' => '44px', // Slightly shorter fields.
),
);
return $presets;
} );

You can also tweak a built-in preset instead of adding one:

// Make the Dark preset use a pure-black panel.
add_filter( 'stitch_payments_style_presets', function ( $presets ) {
$presets['dark']['tokens']['--stitch-form-bg'] = '#000';
return $presets;
} );

Two things to know about precedence:

  1. The Accent color and Custom checkout CSS gateway settings are printed after the preset, so merchant choices win over preset values.
  2. Themes that only need small tweaks can skip presets entirely and override the variables in plain CSS — every token is declared on :root by the form stylesheet:
:root {
--stitch-accent: #ff6600;
--stitch-radius-sm: 2px;
}

The exception is the card-number field, which lives inside CardPointe's iframe: plain CSS can't reach it. --stitch-field-height, --stitch-field-text, and --stitch-field-placeholder do reach it when set through a preset, because the plugin regenerates the iframe CSS from the active preset. For anything beyond that, use stitch_payments_iframe_css.

Style token reference​

Defaults shown are the default preset (they mirror assets/css/stitch-gateway.css).

Colors and accents

TokenDefaultControls
--stitch-accent#3b82f6Focused-field border, selected saved-card border, radio/checkbox color
--stitch-accent-soft#eff6ffBackground of the selected saved-card row
--stitch-focus-ringrgba(59, 130, 246, 0.15)Soft glow around the focused field
--stitch-success#16a34aBorder of a field that passed validation
--stitch-error#dc2626Border and message color of an invalid field
--stitch-error-ringrgba(220, 38, 38, 0.12)Soft glow around an invalid field

Surfaces and panels

TokenDefaultControls
--stitch-surface#fffBackground of inputs, the card-number frame, and saved-card rows
--stitch-surface-soft#f8fafcSubtle secondary background (e.g. the surcharge disclosure box)
--stitch-form-bgtransparentPanel behind the whole payment form (the Dark preset sets this)
--stitch-form-padding0pxInner padding of that panel
--stitch-header-bglinear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%)Header strip behind the logo, icons, and description
--stitch-card-preview-bgdark gradientBackground of the animated card preview graphic

Text

TokenDefaultControls
--stitch-form-textinheritBase text color inside the form panel
--stitch-text-body#475569Description / body copy
--stitch-text-muted#64748bSecondary text (saved-card expiry, "we accept" label)
--stitch-field-textinheritText typed into fields — also applied inside the card-number iframe
--stitch-field-placeholder#9ca3afPlaceholder text — also applied inside the card-number iframe

Borders

TokenDefaultControls
--stitch-field-border#cbd5e1Input borders (resting state)
--stitch-border-soft#e2e8f0Separator line below the header
--stitch-saved-border#dbe3eaBorder of saved-card rows (unselected)

Size and spacing

TokenDefaultControls
--stitch-field-height48pxInput height — also applied inside the card-number iframe
--stitch-field-padding0.75remInner horizontal padding of inputs
--stitch-row-gap1remVertical gap between form rows
--stitch-header-padding1.5remPadding of the header strip
--stitch-radius-sm8pxCorner radius of inputs
--stitch-radius-md10pxCorner radius of saved-card rows
--stitch-radius-lg12pxCorner radius of the form panel and header

Recipes​

Sharp, minimal fields matching a flat theme:

:root {
--stitch-radius-sm: 0;
--stitch-radius-md: 0;
--stitch-radius-lg: 0;
--stitch-header-bg: transparent;
--stitch-border-soft: transparent;
}

Brand-green accents everywhere:

:root {
--stitch-accent: #0a7d4f;
--stitch-accent-soft: #e8f5ef;
--stitch-focus-ring: rgba(10, 125, 79, 0.18);
--stitch-success: #0a7d4f;
}

Denser form for narrow sidebars or modals (heights via preset so the iframe matches):

add_filter( 'stitch_payments_style_presets', function ( $presets ) {
$presets['dense'] = array(
'label' => __( 'Dense', 'my-theme' ),
'tokens' => array(
'--stitch-field-height' => '38px',
'--stitch-field-padding' => '0.5rem',
'--stitch-row-gap' => '0.5rem',
'--stitch-header-padding' => '0.75rem',
),
);
return $presets;
} );

stitch_payments_iframe_css​

Filter the minified CSS injected into the CardPointe tokenizer iframe (the card-number field). Since 0.4.0 this CSS is generated from the active checkout style preset so the field matches the rest of the form; this filter runs last as an escape hatch. See the CardPointe tokenizer docs.

Do not include double quotes in the CSS string (for example around multi-word font-family names). CardPointe rejects the entire css parameter when quotes are present — use unquoted names such as Segoe UI instead.

Parameters: $css (string, minified)

// Use a monospaced font for the card number.
add_filter( 'stitch_payments_iframe_css', function ( $css ) {
return $css . 'input{font-family:ui-monospace,Menlo,monospace;letter-spacing:1px;}';
} );

stitch_payments_customer_decline_message​

Filter the customer-facing message shown when CardPointe declines a payment (since 0.5.2). Processor resptext stays in the payment logs; checkout shows this safer copy on classic and Blocks.

Parameters: $message (string), $error (WP_Error), $respcode (string), $resptext (string)

add_filter( 'stitch_payments_customer_decline_message', function ( $message, $error, $respcode, $resptext ) {
if ( '107' === $respcode ) {
return 'Please call the number on the back of your card, then try again.';
}
return $message;
}, 10, 4 );

stitch_payments_gateway_script_params​

Filter wc_stitch_params, the settings object handed to the classic checkout script (also loaded on Blocks checkout as a shared dependency).

Parameters: $params (array)

$params keys: gateway_id, test_mode, merchant_id, enable_profiles, enable_surcharge, show_card_preview, iframe_url, iframe_css, logo_url, card_brand_icons, accepted_card_icons, i18n_card_number, i18n

// Force the animated card preview off on mobile, whatever the setting says.
add_filter( 'stitch_payments_gateway_script_params', function ( $params ) {
if ( wp_is_mobile() ) {
$params['show_card_preview'] = 'no';
}
return $params;
} );

stitch_payments_blocks_payment_method_data​

Filter all data passed to the Blocks script (assets/dist/stitch-blocks.js) — labels, feature flags, icons, and display settings for the Blocks checkout UI.

Parameters: $data (array), $gateway (Gateway)

// Change the payment method title shown in the Blocks payment list.
add_filter( 'stitch_payments_blocks_payment_method_data', function ( $data, $gateway ) {
$data['title'] = 'Credit card (secure)';
return $data;
}, 10, 2 );

stitch_payments_is_checkout_context​

Filter whether the current request counts as a checkout/payment context. The plugin uses this to decide when its CSS/JS may be needed — override it if you render checkout on a custom page the plugin can't detect.

Parameters: $is_context (bool), $gateway (Gateway)

add_filter( 'stitch_payments_is_checkout_context', function ( $is_context, $gateway ) {
return $is_context || is_page( 'custom-checkout' );
}, 10, 2 );

stitch_payments_should_enqueue_payment_assets​

Filter whether the payment CSS/JS are actually enqueued. Defaults to the result of the checkout-context check above; this is the more forceful switch of the two.

Parameters: $should (bool), $gateway (Gateway)

// Never load Stitch assets on the blog.
add_filter( 'stitch_payments_should_enqueue_payment_assets', function ( $should, $gateway ) {
return is_singular( 'post' ) ? false : $should;
}, 10, 2 );

stitch_payments_hide_native_saved_methods​

Since 0.3.2. Saved Stitch cards are hidden from WooCommerce's own top-level saved-method options at checkout (defaults to true), because paying through the native option would bypass the Stitch payment form and its surcharge disclosure. Saved cards are instead selected inside the Stitch payment method. My Account → Payment methods is unaffected either way.

Parameters: $hide (bool)

// Restore WooCommerce's native saved-card options at checkout
// (not recommended when surcharge disclosure is enabled).
add_filter( 'stitch_payments_hide_native_saved_methods', '__return_false' );

stitch_payments_register_gateway​

Since 0.3.0. Filter whether the Stitch gateway is registered with WooCommerce at all. Returning false removes both the classic and Blocks payment methods — useful for staging environments or conditional rollouts.

Parameters: $register (bool, default true)

// Disable Stitch on staging only.
add_filter( 'stitch_payments_register_gateway', function ( $register ) {
return ( defined( 'WP_ENVIRONMENT_TYPE' ) && 'staging' === WP_ENVIRONMENT_TYPE )
? false
: $register;
} );

stitch_payments_allowed_api_hosts​

Since 0.4.0. The test/production base URL override settings only accept hosts on CardPointe domains (cardconnect.com, cardpointe.com), so API credentials cannot be sent to an arbitrary host through a mistyped or tampered setting. If your merchant account runs on a white-label CardPointe host, add its domain here. Overrides must be bare hostnames (no port, path, or user@); anything rejected falls back to the default CardPointe endpoint and logs a warning to the wc-stitch-api log.

Parameters: $allowed (array of domain suffixes; an override host must equal a suffix or be a subdomain of it)

// Allow a white-label CardPointe host such as api.mypartner.example.
add_filter( 'stitch_payments_allowed_api_hosts', function ( $allowed ) {
$allowed[] = 'mypartner.example';
return $allowed;
} );

stitch_payments_max_charge_amount​

Since 0.8.0. The largest single charge the gateway will send to CardPointe, in the order currency. It is a guard against a corrupted order total, not a business limit. An order, renewal, or pre-order release above it is refused before anything is sent.

Parameters: $max (float, default 100000)

// Refuse any single charge over 5,000.
add_filter( 'stitch_payments_max_charge_amount', function ( $max ) {
return 5000.0;
} );

stitch_payments_surcharge_rate_limit​

Since 0.8.0. Every card fee check is a CardPointe call that reveals whether a card is credit or debit, so one shopper can only make a limited number per window. Over the limit, the checkout shows "Too many card checks. Please wait a few minutes and try again."

Parameters: $rate (array with limit — checks per window, default 20 — and window — seconds, default 600, minimum 60). A limit of 0 turns the limit off.

add_filter( 'stitch_payments_surcharge_rate_limit', function ( $rate ) {
$rate['limit'] = 40;
return $rate;
} );

stitch_payments_surcharge_unconfirmed_alert_threshold​

Since 0.8.0. When the card fee cannot be confirmed at payment, the order still goes through and is flagged. This filter sets how many such orders in 24 hours make the admin warning appear on WooCommerce screens. See Surcharge.

Parameters: $threshold (int, default 3). 0 turns the warning off; orders are still flagged and logged.

add_filter( 'stitch_payments_surcharge_unconfirmed_alert_threshold', function ( $threshold ) {
return 10;
} );

stitch_payments_debug_log​

Since 0.8.0. Whether successful API calls are written to the wc-stitch-api log. Failures are always logged. Defaults to the Debug log setting. Names, addresses, expiry dates, tokens, and security codes are redacted either way.

Parameters: $enabled (bool)

// Full API logging on staging only.
add_filter( 'stitch_payments_debug_log', function ( $enabled ) {
return 'staging' === wp_get_environment_type() ? true : $enabled;
} );

stitch_payments_ach_authorization_text​

Since 0.8.0. The sentence a shopper accepts before a bank debit. The accepted text is stored on the order with a timestamp and the shopper's IP address.

Parameters: $text (string), $gateway (the bank account gateway)

add_filter( 'stitch_payments_ach_authorization_text', function ( $text, $gateway ) {
return $text . ' Questions? Email billing@example.com.';
}, 10, 2 );

WooCommerce admin filters​

Standard WooCommerce settings-API filters also apply to the gateway's settings screen:

// Hide the card preview toggle from the settings screen.
add_filter( 'woocommerce_settings_api_form_fields_stitch', function ( $fields ) {
unset( $fields['show_card_preview'] );
return $fields;
} );
  • woocommerce_settings_api_form_fields_stitch — filter the settings form fields
  • woocommerce_settings_api_sanitized_fields_stitch — filter values as they are saved

Actions (classic checkout only)​

These fire while payment-form.php renders, so anything you echo appears at that position. They do not run on Blocks checkout (React renders that form).

HookFiresParameters
stitch_payments_before_payment_formBefore the payment <fieldset>$gateway, $saved_methods
stitch_payments_after_payment_headerAfter the logo / icons / description$gateway, $checkout_display, $saved_methods
stitch_payments_before_new_card_fieldsBefore the new-card inputs$gateway, $saved_methods
stitch_payments_after_payment_formAfter the closing </fieldset>$gateway, $saved_methods
// A reassurance note above the form.
add_action( 'stitch_payments_before_payment_form', function ( $gateway, $saved_methods ) {
echo '<p class="stitch-checkout-notice">Cards are processed securely by CardPointe.</p>';
}, 10, 2 );

// A hint above the new-card fields, only for customers with saved cards.
add_action( 'stitch_payments_before_new_card_fields', function ( $gateway, $saved_methods ) {
if ( array() !== $saved_methods ) {
echo '<p class="stitch-new-card-hint">Adding a new card? You can save it for next time below.</p>';
}
}, 10, 2 );

Bootstrap​

stitch_payments_loaded​

Fires once after the plugin has loaded its core services — the safe point to interact with Stitch classes from other plugins.

add_action( 'stitch_payments_loaded', function () {
// Stitch classes are available from here on.
if ( class_exists( \StitchPayments\WooCommerce\Payments\Style_Presets::class ) ) {
// e.g. read the registered presets.
}
} );

stitch_payments_surcharge_unconfirmed​

Since 0.8.0. Fires when an order is paid without CardPointe confirming its card fee, after the order has been flagged and logged.

Parameters: $order (WC_Order), $count (int — unconfirmed orders in the last 24 hours)

add_action( 'stitch_payments_surcharge_unconfirmed', function ( $order, $count ) {
if ( $count >= 3 ) {
wp_mail( get_option( 'admin_email' ), 'Stitch card fee check failing', "Order {$order->get_order_number()} was paid without a confirmed fee." );
}
}, 10, 2 );

stitch_payments_ach_payment_returned​

Since 0.8.0. Fires when a bank payment that had already cleared is returned by the bank. Orders in Processing go back to On hold so they are not shipped, and the store admin is emailed.

Parameters: $order (WC_Order), $code (string — the ACH return code, for example R01)

add_action( 'stitch_payments_ach_payment_returned', function ( $order, $code ) {
$order->add_order_note( 'Bank return code: ' . $code );
}, 10, 2 );

stitch_payments_saved_card_closed​

Since 0.8.0. Fires just before the daily Card Account Updater removes a saved card the issuer reports as closed or invalid. Use it to email the customer or to flag subscriptions that use the card.

Parameters: $token (WC_Payment_Token_CC, gateway stitch), $status (string — CLOSED or NOGOOD)

add_action( 'stitch_payments_saved_card_closed', function ( $token, $status ) {
$user = get_userdata( $token->get_user_id() );
if ( $user ) {
wp_mail( $user->user_email, 'Please update your card', 'The card ending ' . $token->get_last4() . ' can no longer be used.' );
}
}, 10, 2 );

Blocks vs classic​

FeatureClassicBlocks
PHP template overrideYesNo
Action hooksYesNo
stitch_payments_payment_form_i18nYesYes
stitch_payments_saved_payment_methodsYesYes
stitch_payments_blocks_payment_method_dataNoYes
stitch_payments_gateway_script_paramsYesShared JS dependency

Prefer stitch_payments_payment_form_i18n and stitch_payments_saved_payment_methods when you need both checkout types to stay aligned.