Extend Stitch Payments
This guide covers extending Stitch Payments for WooCommerce in themes, child themes, and companion plugins.
Start with the lightest change
| Goal | Approach |
|---|---|
| Restyle the form | CSS on #wc-stitch-form, .stitch-payment-header, etc. |
| Change labels or copy | Admin settings or stitch_payments_checkout_field_labels / stitch_payments_payment_form_i18n |
| Change logo or branding | Admin settings or stitch_payments_checkout_display_settings |
| Inject HTML (classic) | Action hooks in the payment template |
| Replace classic markup | Theme template override |
| Change Blocks data | stitch_payments_blocks_payment_method_data |
| Style card-number iframe | stitch_payments_iframe_css |
| Customize decline messages | stitch_payments_customer_decline_message |
| Custom checkout page | stitch_payments_is_checkout_context |
Use these filters instead of calling gateway methods. Filters keep classic and Blocks checkout aligned and survive internal refactors. The copy-paste steps for a template override are on Customization.
Gateway ID
The WooCommerce gateway ID is always stitch. Do not change it without a data migration plan — existing orders, subscriptions, and payment tokens depend on this ID.
Architecture
The gateway is composed of focused service classes. The Gateway object owns credentials, settings, and the WooCommerce contract, and delegates presentation and processing to dedicated collaborators.
| Component | Location |
|---|---|
| Gateway | includes/Payments/class-gateway.php |
| Checkout presentation (labels, branding, saved methods, i18n, iframe CSS) | includes/Payments/Checkout/class-checkout-display.php |
| Payment processing entry point (delegates to the classes below) | includes/Payments/Processing/class-payment-processor.php |
| Posted card details and saved-card ownership checks | includes/Payments/Processing/class-checkout-payment-data.php |
| Authorization payload (amount, Level 2 / 3) | includes/Payments/Processing/class-auth-payload-builder.php |
| Sending authorizations, timeout recovery, per-attempt order ID | includes/Payments/Processing/class-authorization-attempts.php |
| Writing an approved payment to the order | includes/Payments/Processing/class-order-payment-recorder.php |
| AVS / CVV hold or void | includes/Payments/Processing/class-verification-handler.php |
| Capture or void of authorize-only orders | includes/Payments/Processing/class-deferred-capture.php |
| Renewals and pre-order release on a stored profile | includes/Payments/Processing/class-stored-card-payments.php |
| Saving a card with a $0 check (card change, pre-order) | includes/Payments/Processing/class-card-enrollment.php |
| Refunds and voids | includes/Payments/Processing/class-refund-processor.php |
| Saved cards and My Account add-card | includes/Payments/Processing/class-saved-card-store.php |
| Saved card as a WooCommerce card token (profile, account, scope) | includes/Payments/Processing/class-card-token.php |
| Card Account Updater | includes/Payments/Processing/class-card-account-updater.php |
| Level 2 / 3 commercial fields | includes/Payments/Processing/class-level-data.php |
| AVS / CVV no-match policy | includes/Payments/Processing/class-verification-policy.php |
| WooCommerce Pre-Orders release hook | includes/Payments/Processing/class-pre-order-support.php |
| Gateway settings screen | includes/Payments/Admin/class-admin-settings.php |
| Settings field definitions | includes/Payments/Admin/class-settings-fields.php |
| Customer-facing decline message mapping | includes/Payments/Checkout/class-decline-messages.php |
| Admin hero & live checkout preview | includes/Payments/Admin/class-admin-preview.php |
| My Account saved-method display | includes/Payments/Checkout/class-account-payment-methods.php |
| Subscriptions (renewals, meta copy) | includes/Payments/Processing/class-subscription-support.php |
| Surcharge calculation and persistence | includes/Payments/Surcharge/class-surcharge-service.php |
| Surcharge disclosure markup | includes/Payments/Surcharge/class-surcharge-disclosure.php |
| Blocks checkout payment fields | includes/Payments/Checkout/class-store-api-payment-data.php |
| CardPointe API endpoints | includes/API/class-client.php |
| HTTP, retries, and error mapping | includes/API/class-http-transport.php |
| API call logging | includes/API/class-api-logger.php |
| API log redaction | includes/API/class-log-redactor.php |
| Order transaction meta box | includes/Payments/Admin/class-order-meta-box.php |
| Blocks integration | includes/Payments/Checkout/class-blocks-integration.php |
| Checkout context detection | includes/Payments/Checkout/class-checkout-context.php |
| Classic template | templates/payment-form.php |
| Classic JS | assets/js/stitch-gateway.js |
| Checkout field validation | assets/js/stitch-validation.js |
| Surcharge checkout script | assets/js/stitch-surcharge.js |
| Blocks JS (built, card) | assets/dist/stitch-blocks.js, source in src/blocks/card/ |
| Blocks JS (built, bank account) | assets/dist/stitch-ach-blocks.js, source in src/blocks/ach/ |
| Blocks script registration | includes/Payments/Checkout/class-blocks-script.php |
| Styles | assets/css/stitch-gateway.css |
:::note Since 0.8.0
Payment_Processor and API\Client were split into the focused classes above. The public methods on Payment_Processor (process_payment(), process_refund(), process_subscription_payment(), process_pre_order_release(), capture_authorized_payment(), void_authorized_payment()) and the gateway's payment_processor() accessor are unchanged.
The Blocks scripts are built with @wordpress/scripts from src/blocks/ into assets/dist/, and the built files are committed. The release zip contains assets/dist/ but not src/, node_modules/, or the build config, so installing the plugin needs no Node. To change them, run npm ci and npm run build (Node 22 or newer, see .nvmrc) and commit the rebuilt assets/dist/ with the source. CI fails if assets/dist/ does not match src/.
:::
:::note Since 0.3.0
The gateway was refactored from a single large class into the service classes above. Behavior is unchanged, but some public helper methods moved off Gateway — see Public gateway helpers below.
:::
:::note Since 0.3.2 Behavior changes to be aware of when integrating:
is_available()returnsfalsefor non-USD stores — the gateway is hidden at checkout unless the store currency is USD.- Money-moving API calls are single-attempt — the API client no longer retries authorizations, refunds, or profile saves after a timeout. Idempotent calls (voids, inquiries) still retry. If an authorization is interrupted without a usable response, the payment processor inquires by order ID and adopts the approved transaction if one exists.
- Saved-method ownership is enforced — profile/account IDs submitted at checkout (and to the surcharge AJAX endpoint) must belong to the current customer's payment tokens.
- The webhook URL setting was removed — there was no handler behind it; it will return when webhook processing ships. :::
:::note Since 0.5.0
- Guests can check out —
is_available()no longer requires a logged-in user. Saved-card UI is gated byGateway::profiles_enabled_for_current_user()(profiles enabled and logged in). Guests can only pay with a new card; ownership checks still reject user ID 0. - Authorize-only payments —
Gateway::$capture_modeissaleorauthorize. Checkout auth sendscapture: YorN. Capture and void run from order-status hooks inGateway_Loader(Processing/Completed capture; Cancelled voids). Use$gateway->payment_processor()to reachcapture_authorized_payment()/void_authorized_payment(). Subscription renewals always sendcapture: Y. :::
:::note Since 0.5.4
- Level 2 / 3 fields are appended in
Level_Datawhenenable_level3isyes. The amount sent is the order total, minus a Credit card surcharge fee when that fee is on the order. - Pre-order release is
Payment_Processor::process_pre_order_release(), hooked byPre_Order_Supportonwc_pre_orders_process_pre_order_completion_payment_stitch. - AVS / CVV policy is decided by
Verification_Policy. Only response codeNis a mismatch. Renewals and pre-order release charges skip it. - Add payment method is
Saved_Card_Store::add_payment_method(): a $0 verification, then profile save. Posted profile IDs are ignored. :::
:::note Since 0.5.5
Payment classes are grouped into Checkout, Processing, Admin, and Surcharge under includes/Payments/. The namespace is still StitchPayments\WooCommerce\Payments.
:::
:::note Since 0.6.0
- Surcharge is an order fee after a CardPointe quote.
Payment_Processorleaves that fee out of the authorization amount. - Renewals send
ecomindR. Pre-order release staysecomindE. - Saved cards (from 0.8.0) are standard WooCommerce credit card tokens: type
CC, gatewaystitch. Card type, last four, and expiry are the token's own properties. The CardPointe profile and account IDs and the saved-under environment and merchant are token meta, read and written throughCard_Token(stitch_profile_id,stitch_acct_id,stitch_environment,stitch_merchant_id). The cardholder name is not stored. A card needs a card type, last four, and expiry to be saved. - Token deletion calls
Saved_Card_Store::delete_remote_profile()onwoocommerce_payment_token_deleted, which deletes that profile account only. - Card Account Updater runs on the daily
stitch_sync_card_account_updateshook. It reads profile updates. It does not write accounts into the updater. - Unconfirmed authorizations that time out with no approved inquiry are voided with
voidByOrderId. :::
:::note Since 0.6.1
- Save card note is
Checkout_Display::get_save_card_note(). Allowed tags arestrong,em,b,i, andbr. :::
Getting the gateway instance
use StitchPayments\WooCommerce\Payments\Gateway;
function stitch_get_gateway(): ?Gateway {
if ( ! function_exists( 'WC' ) || ! WC()->payment_gateways() ) {
return null;
}
$gateways = WC()->payment_gateways()->payment_gateways();
return isset( $gateways['stitch'] ) && $gateways['stitch'] instanceof Gateway
? $gateways['stitch']
: null;
}
Call after WooCommerce has registered gateways (e.g. on woocommerce_init or later).
Bootstrap hook
add_action( 'stitch_payments_loaded', function () {
// Register integrations that depend on Stitch.
} );
Public gateway helpers
:::warning Changed in 0.3.0
These checkout-presentation helpers moved from Gateway to the Checkout_Display class. Access them through the $gateway->checkout_display() accessor instead of calling them directly on the gateway.
// Before (0.2.x)
$labels = $gateway->get_checkout_field_labels();
// Now (0.3.0+)
$labels = $gateway->checkout_display()->get_checkout_field_labels();
:::
Available on $gateway->checkout_display():
| Method | Purpose |
|---|---|
get_checkout_field_labels() | Field labels (classic + Blocks) |
get_checkout_display_settings() | Logo, icons, description toggles |
get_payment_form_i18n() | Shared UI and validation strings |
get_saved_payment_methods_for_checkout() | Saved methods keyed by account ID |
get_saved_payment_methods_for_blocks() | Blocks-formatted saved methods |
get_default_saved_account_id( $methods ) | Default selected saved card |
get_iframe_css() | CardPointe tokenizer iframe CSS |
get_checkout_logo_url() | Resolved logo URL |
Checkout_Context::is_checkout_context( $gateway ) detects checkout, shortcode pages, and Elementor layouts.
Available on $gateway itself:
| Method | Purpose |
|---|---|
profiles_enabled_for_current_user() | Saved-card UI for this visitor (profiles enabled and logged in) |
payment_processor() | Auth, capture, refund, void, and renewal engine |
checkout_display() | Presentation helper (table above) |
For most customizations you should prefer the filters over calling these helpers directly — filters keep classic and Blocks checkout aligned and survive internal refactors.