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
| Hook | Type | Use it to… |
|---|---|---|
stitch_payments_payment_form_template_args | Filter | Change anything passed to the classic payment form template |
stitch_payments_checkout_field_labels | Filter | Rename the card fields |
stitch_payments_checkout_display_settings | Filter | Override branding (logo, icons, description) in code |
stitch_payments_payment_form_i18n | Filter | Reword any UI or validation message |
stitch_payments_saved_payment_methods | Filter | Hide or reorder saved cards at checkout |
stitch_payments_accepted_card_brands | Filter | Change which brand icons appear in the header |
stitch_payments_payment_header_html | Filter | Rewrite the rendered header HTML |
stitch_payments_style_presets | Filter | Register your own checkout style preset |
stitch_payments_iframe_css | Filter | Restyle the card-number field inside the CardPointe iframe |
stitch_payments_customer_decline_message | Filter | Customize decline messages shown to customers |
stitch_payments_gateway_script_params | Filter | Adjust data passed to the classic checkout script |
stitch_payments_blocks_payment_method_data | Filter | Adjust data passed to the Blocks checkout script |
stitch_payments_is_checkout_context | Filter | Teach the plugin about custom checkout pages |
stitch_payments_should_enqueue_payment_assets | Filter | Force or block CSS/JS loading |
stitch_payments_hide_native_saved_methods | Filter | Restore WooCommerce's native saved-card options |
stitch_payments_register_gateway | Filter | Conditionally disable the gateway |
stitch_payments_allowed_api_hosts | Filter | Allow a white-label CardPointe API host |
stitch_payments_max_charge_amount | Filter | Change the largest single charge the gateway will send |
stitch_payments_surcharge_rate_limit | Filter | Change how many card fee checks one shopper can make |
stitch_payments_surcharge_unconfirmed_alert_threshold | Filter | Change when the admin is warned about unconfirmed card fees |
stitch_payments_debug_log | Filter | Turn full API logging on or off in code |
stitch_payments_ach_authorization_text | Filter | Reword the bank debit authorization |
stitch_payments_before_payment_form and friends | Action | Print custom content around the classic form |
stitch_payments_loaded | Action | Run code once the plugin has booted |
stitch_payments_surcharge_unconfirmed | Action | React to an order paid without a confirmed card fee |
stitch_payments_ach_payment_returned | Action | React to a bank payment the bank returned after it cleared |
stitch_payments_saved_card_closed | Action | React 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' ) );
} );
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 · 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:
- The Accent color and Custom checkout CSS gateway settings are printed after the preset, so merchant choices win over preset values.
- Themes that only need small tweaks can skip presets entirely and override the variables in plain CSS — every token is declared on
:rootby 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
| Token | Default | Controls |
|---|---|---|
--stitch-accent | #3b82f6 | Focused-field border, selected saved-card border, radio/checkbox color |
--stitch-accent-soft | #eff6ff | Background of the selected saved-card row |
--stitch-focus-ring | rgba(59, 130, 246, 0.15) | Soft glow around the focused field |
--stitch-success | #16a34a | Border of a field that passed validation |
--stitch-error | #dc2626 | Border and message color of an invalid field |
--stitch-error-ring | rgba(220, 38, 38, 0.12) | Soft glow around an invalid field |
Surfaces and panels
| Token | Default | Controls |
|---|---|---|
--stitch-surface | #fff | Background of inputs, the card-number frame, and saved-card rows |
--stitch-surface-soft | #f8fafc | Subtle secondary background (e.g. the surcharge disclosure box) |
--stitch-form-bg | transparent | Panel behind the whole payment form (the Dark preset sets this) |
--stitch-form-padding | 0px | Inner padding of that panel |
--stitch-header-bg | linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%) | Header strip behind the logo, icons, and description |
--stitch-card-preview-bg | dark gradient | Background of the animated card preview graphic |
Text
| Token | Default | Controls |
|---|---|---|
--stitch-form-text | inherit | Base text color inside the form panel |
--stitch-text-body | #475569 | Description / body copy |
--stitch-text-muted | #64748b | Secondary text (saved-card expiry, "we accept" label) |
--stitch-field-text | inherit | Text typed into fields — also applied inside the card-number iframe |
--stitch-field-placeholder | #9ca3af | Placeholder text — also applied inside the card-number iframe |
Borders
| Token | Default | Controls |
|---|---|---|
--stitch-field-border | #cbd5e1 | Input borders (resting state) |
--stitch-border-soft | #e2e8f0 | Separator line below the header |
--stitch-saved-border | #dbe3ea | Border of saved-card rows (unselected) |
Size and spacing
| Token | Default | Controls |
|---|---|---|
--stitch-field-height | 48px | Input height — also applied inside the card-number iframe |
--stitch-field-padding | 0.75rem | Inner horizontal padding of inputs |
--stitch-row-gap | 1rem | Vertical gap between form rows |
--stitch-header-padding | 1.5rem | Padding of the header strip |
--stitch-radius-sm | 8px | Corner radius of inputs |
--stitch-radius-md | 10px | Corner radius of saved-card rows |
--stitch-radius-lg | 12px | Corner 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 fieldswoocommerce_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).
| Hook | Fires | Parameters |
|---|---|---|
stitch_payments_before_payment_form | Before the payment <fieldset> | $gateway, $saved_methods |
stitch_payments_after_payment_header | After the logo / icons / description | $gateway, $checkout_display, $saved_methods |
stitch_payments_before_new_card_fields | Before the new-card inputs | $gateway, $saved_methods |
stitch_payments_after_payment_form | After 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
| Feature | Classic | Blocks |
|---|---|---|
| PHP template override | Yes | No |
| Action hooks | Yes | No |
stitch_payments_payment_form_i18n | Yes | Yes |
stitch_payments_saved_payment_methods | Yes | Yes |
stitch_payments_blocks_payment_method_data | No | Yes |
stitch_payments_gateway_script_params | Yes | Shared JS dependency |
Prefer stitch_payments_payment_form_i18n and stitch_payments_saved_payment_methods when you need both checkout types to stay aligned.