Skip to main content

Extend Stitch Payments

This guide covers extending Stitch Payments for WooCommerce in themes, child themes, and companion plugins.

Start with the lightest change​

GoalApproach
Restyle the formCSS on #wc-stitch-form, .stitch-payment-header, etc.
Change labels or copyAdmin settings or stitch_payments_checkout_field_labels / stitch_payments_payment_form_i18n
Change logo or brandingAdmin settings or stitch_payments_checkout_display_settings
Inject HTML (classic)Action hooks in the payment template
Replace classic markupTheme template override
Change Blocks datastitch_payments_blocks_payment_method_data
Style card-number iframestitch_payments_iframe_css
Customize decline messagesstitch_payments_customer_decline_message
Custom checkout pagestitch_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.

ComponentLocation
Gatewayincludes/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 checksincludes/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 IDincludes/Payments/Processing/class-authorization-attempts.php
Writing an approved payment to the orderincludes/Payments/Processing/class-order-payment-recorder.php
AVS / CVV hold or voidincludes/Payments/Processing/class-verification-handler.php
Capture or void of authorize-only ordersincludes/Payments/Processing/class-deferred-capture.php
Renewals and pre-order release on a stored profileincludes/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 voidsincludes/Payments/Processing/class-refund-processor.php
Saved cards and My Account add-cardincludes/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 Updaterincludes/Payments/Processing/class-card-account-updater.php
Level 2 / 3 commercial fieldsincludes/Payments/Processing/class-level-data.php
AVS / CVV no-match policyincludes/Payments/Processing/class-verification-policy.php
WooCommerce Pre-Orders release hookincludes/Payments/Processing/class-pre-order-support.php
Gateway settings screenincludes/Payments/Admin/class-admin-settings.php
Settings field definitionsincludes/Payments/Admin/class-settings-fields.php
Customer-facing decline message mappingincludes/Payments/Checkout/class-decline-messages.php
Admin hero & live checkout previewincludes/Payments/Admin/class-admin-preview.php
My Account saved-method displayincludes/Payments/Checkout/class-account-payment-methods.php
Subscriptions (renewals, meta copy)includes/Payments/Processing/class-subscription-support.php
Surcharge calculation and persistenceincludes/Payments/Surcharge/class-surcharge-service.php
Surcharge disclosure markupincludes/Payments/Surcharge/class-surcharge-disclosure.php
Blocks checkout payment fieldsincludes/Payments/Checkout/class-store-api-payment-data.php
CardPointe API endpointsincludes/API/class-client.php
HTTP, retries, and error mappingincludes/API/class-http-transport.php
API call loggingincludes/API/class-api-logger.php
API log redactionincludes/API/class-log-redactor.php
Order transaction meta boxincludes/Payments/Admin/class-order-meta-box.php
Blocks integrationincludes/Payments/Checkout/class-blocks-integration.php
Checkout context detectionincludes/Payments/Checkout/class-checkout-context.php
Classic templatetemplates/payment-form.php
Classic JSassets/js/stitch-gateway.js
Checkout field validationassets/js/stitch-validation.js
Surcharge checkout scriptassets/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 registrationincludes/Payments/Checkout/class-blocks-script.php
Stylesassets/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() returns false for 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 by Gateway::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_mode is sale or authorize. Checkout auth sends capture: Y or N. Capture and void run from order-status hooks in Gateway_Loader (Processing/Completed capture; Cancelled voids). Use $gateway->payment_processor() to reach capture_authorized_payment() / void_authorized_payment(). Subscription renewals always send capture: Y. :::

:::note Since 0.5.4

  • Level 2 / 3 fields are appended in Level_Data when enable_level3 is yes. 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 by Pre_Order_Support on wc_pre_orders_process_pre_order_completion_payment_stitch.
  • AVS / CVV policy is decided by Verification_Policy. Only response code N is 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_Processor leaves that fee out of the authorization amount.
  • Renewals send ecomind R. Pre-order release stays ecomind E.
  • Saved cards (from 0.8.0) are standard WooCommerce credit card tokens: type CC, gateway stitch. 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 through Card_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() on woocommerce_payment_token_deleted, which deletes that profile account only.
  • Card Account Updater runs on the daily stitch_sync_card_account_updates hook. 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 are strong, em, b, i, and br. :::

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():

MethodPurpose
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:

MethodPurpose
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)
tip

For most customizations you should prefer the filters over calling these helpers directly — filters keep classic and Blocks checkout aligned and survive internal refactors.

Next steps​