Stitch Payments release notes
All notable changes to Stitch Payments for WooCommerce are documented here.
0.8.0 — 2026-11-09
A larger release: renamed hooks, tighter surcharge and saved-card handling, bank account authorization, and less payment data in the database.
:::warning Before you update
- Hook and filter names changed (see Changed). Old names still work and log a deprecation notice, so move custom code to the new names at your own pace.
- A subscription renewal or pre-order release now charges only the card assigned to it. It no longer falls back to the customer's default saved card. :::
New
wp-config.phpcredentials. Define constants such asSTITCH_PROD_API_PASSWORDto keep secrets out of the database. A constant overrides the saved value and the settings field is locked. See Getting started.- Action Scheduler. The daily Card Account Updater sync and the twice-daily bank funding check run on Action Scheduler instead of WP-Cron.
- One order ID per attempt. Each authorization attempt sends its own order ID to CardPointe (
123, then123-2), so a retry cannot collide with the first attempt. The newstitch_payments_max_charge_amountfilter caps a single charge (default 100,000). - Surcharge checked at payment. The fee is checked again with the real card when the customer pays. A changed fee sends the customer back to review the new total before anything is charged. See Surcharge.
- Unconfirmed surcharge flag. If CardPointe cannot confirm the fee at that final check, the payment goes ahead without a fee change, the order is noted and flagged, the failure is logged to
wc-stitch-surcharge, and shop managers see a warning after 3 such orders in 24 hours. - Better surcharge quotes. The fee is quoted on items, tax, shipping, and shipping tax after discounts, is quoted again when the cart changes, refreshes on Blocks checkout, and the lookup is rate limited per shopper.
- Subscription payment method change. My Account Change payment verifies the new card with a $0 authorization and takes no payment. Store managers can edit the profile and account IDs on the subscription screen.
- Bank account authorization. Customers accept a debit authorization that is stored on the order. Bank payments are USD only, need HTTPS in live mode, recover timeouts by looking the debit up instead of resending it, and a return up to 60 days after clearing puts the order on hold and emails the admin. See Bank account payments.
stitch_payments_saved_card_closedaction fires when Card Account Updater removes a closed card.
Changed
- Hooks renamed. Every filter and action is now
stitch_payments_*instead ofwoocommerce_stitch_*. See Hooks and filters. - Saved cards are standard WooCommerce card tokens. They are
WC_Payment_Token_CCtokens for gatewaystitchinstead of a customstitchtoken type, so checkout, Checkout Blocks, My Account, and Subscriptions show them natively. The CardPointe profile and account IDs are token meta, and the cardholder name is no longer stored. A card is saved only when CardPointe returns a card type, last four, and expiry for it. - Saved cards are scoped. Each card records the environment and merchant ID it was saved under and is only offered and charged there. A card with no recorded scope is not offered.
- Internal code split.
Payment_Processorand the API client are split into focused classes, and the Checkout Blocks scripts are built with@wordpress/scriptsfromsrc/blocks/intoassets/dist/. Public methods and filters are unchanged. See the developer overview. - One profile per customer. Each customer has one CardPointe profile per environment and merchant. Profiles from earlier versions keep being reused, so customers do not get a second profile.
- No default-card fallback for renewals and pre-orders. They charge only the card assigned to them.
- Less data in the database. On Blocks checkout the card token, expiry, name, CVV, and bank details are held in memory for the request and no longer written to order meta. The CVV is still never stored. The card number stays in the CardPointe iframe, and expiry and CVV are typed on the store page. See Data and privacy.
- Logs. Entries redact customer name, address, phone, email, and expiry. Successful API calls are logged only while Debug log is on.
- Uninstall cleanup covers every site on a multisite network.
Fixed
- The release package no longer includes
.fuse_hidden*files.
0.7.0 — 2026-10-08
Compatibility update for the current WordPress and WooCommerce releases.
Compatibility
- Tested with WordPress 7.1.3 and WooCommerce 11.2.0
- Plugin headers stay
Tested up to: 7.1andWC tested up to: 11.2
0.6.1 — 2026-09-30
A short explanation under the save-card checkbox.
Added
- Save card note — logged-in customers see a note under Save card for future purchases. It says Stitch Payments stores the card in a secure vault, the store keeps only the last four digits, the expiry, and a reference, and the security code is never saved. Edit it under Other settings → Save card note while Enable Stored Payment Methods is on. Allowed HTML is
strong,em,b,i, andbr. Clear the field to keep the checkbox without the note. See Stored payment methods.
Fixed
- Authorize-only capture — capturing a held payment sends the same amount as the original authorization. A credit card surcharge fee on the order is not sent again.
Compatibility
- Tested with WordPress 7.1.2 and WooCommerce 11.1.2
- Plugin headers stay
Tested up to: 7.1andWC tested up to: 11.1
0.6.0 — 2026-09-30
Surcharge on the order, stricter saved-card behavior, and CardPointe profile maintenance.
Added
- Surcharge fee line — after CardPointe returns a surcharge for the card, that amount is added to the WooCommerce order as a Credit card surcharge fee. The amount sent to CardPointe does not include the fee, because CardPointe applies it on top of the authorized amount. The fee is not added before that quote, and a response that only says bin information was not found does not add a fee. The settings screen no longer has a surcharge rate; the rate is the one boarded on the merchant account. See Surcharge.
- Save card only when checked — a new card is stored only when the customer checks Save card for future purchases. An unchecked field on Blocks checkout no longer saves the card. Subscription checkout still stores the card, because the renewal needs it.
- Card Account Updater — saved profiles are enrolled when the merchant account has the service. Once a day the plugin reads profile updates and refreshes the saved card's expiry and last four, or removes a card the brand reports as closed or invalid. See Stored payment methods.
- Void by order ID — if an authorization times out and an order inquiry does not find an approved transaction, the plugin voids that authorization by order ID. An approved transaction is kept, including one whose amount does not match.
- Delete the stored card at CardPointe — removing a saved card in WooCommerce deletes that profile account at CardPointe. Other cards on the same profile stay stored.
Changed
- Recurring renewals — a scheduled subscription renewal is sent as a recurring charge. A pre-order release charge stays a one-time merchant-initiated charge on the saved profile.
Fixed
- Unsettled refunds — a refund CardPointe declines because the transaction has not settled tells the merchant to wait. A partial refund is refused until settlement. The full remaining amount of an unsettled charge is still voided, so the WooCommerce refund button stays available. See Features.
- Surcharge order note — payment details say the surcharge is included in the order total and is not sent again in the charge.
- Rate limits — CardPointe HTTP 429 responses on inquire, profile, funding, and settlement-status calls are not retried.
Security
- Card merchant ID — the merchant ID saved for card payments must be numeric. An ACH processor ID is rejected in settings and on card API calls. ACH is not a payment method in this release.
Compatibility
- Tested with WordPress 7.1.2 and WooCommerce 11.1.2
- Plugin headers stay
Tested up to: 7.1andWC tested up to: 11.1
0.5.5 — 2026-09-24
Compatibility refresh and a clearer layout of the payment code.
Changed
- Payment code folders — gateway classes are grouped into
includes/Payments/Checkout,Processing,Admin, andSurcharge. The gateway and its loader stay inincludes/Payments. Class names, theStitchPayments\WooCommerce\Paymentsnamespace, and thestitchgateway ID are unchanged. See Developer overview.
Fixed
- Release package — the zip no longer includes
.distignoreor other hidden development files. - Uninstall token cleanup — stored Stitch tokens are selected with a prepared
%itable identifier.
Compatibility
- Tested with WordPress 7.1.2 and WooCommerce 11.1.2
- Plugin headers stay
Tested up to: 7.1andWC tested up to: 11.1
0.5.4 — 2026-09-21
Commercial card data, WooCommerce Pre-Orders, optional address and CVV checks, and adding a card from My Account.
Added
- Level 2 / 3 data — authorization and capture send tax, freight, PO number, ship-to and ship-from ZIP, order date, and line items so corporate and purchasing cards can qualify for better interchange. Level 2 / 3 data under Other settings is on by default. An order with tax is sent as not exempt with a positive tax amount; an order with no tax is sent as tax exempt and omits the tax amount. The amount charged stays the WooCommerce order total. See Commercial card data.
- WooCommerce Pre-Orders — an upfront pre-order is charged at checkout. Pay-upon-release stores the logged-in customer's card with a $0 verification, then charges that saved profile when the pre-order is released, the same way a subscription renewal is charged. Guests are asked to log in. See Stored payment methods.
- AVS and CVV no-match actions — AVS no-match and CVV no-match each offer Accept the payment (the default), Hold the order for review, or Void and decline checkout. Only a CardPointe code of
Nis a mismatch. Partial AVS matches are accepted. If both fail, void wins. The check runs on customer checkout and on the pre-order $0 verification. It does not run on subscription renewals or pre-order release charges. See Address and CVV checks. - Add a card in My Account — a logged-in customer can save a card from My Account → Payment methods → Add payment method without placing an order. The card is checked with a $0 authorization. The CVV is used only for that check and is never stored.
Changed
- Saved cards, the settings screen, refunds, checkout field validation, the surcharge disclosure, API log redaction, and Blocks checkout field mapping now live in their own files. Authorization, capture, and renewals stay in the payment processor.
Compatibility
- Tested with WordPress 7.1.1 and WooCommerce 11.1.1
- Updated plugin header:
WC tested up to: 11.1(Tested up toremains 7.1)
0.5.3 — 2026-09-16
Surcharge disclosure on mobile Blocks checkout.
Fixed
- Mobile order-summary surcharge note — on Blocks checkout, the surcharge disclosure under the order total now also appears on mobile. WooCommerce Blocks shows duplicate order summaries on small screens (collapsible top summary and another near Place order); the note previously only targeted the desktop sidebar. It now uses WooCommerce's
ExperimentalOrderMetaSlot Fill so every summary instance shows the disclosure. See Surcharge.
0.5.2 — 2026-09-16
Clearer decline messages at checkout, and a fix for CardPointe tokenizer iframe styling.
Fixed
- Meaningful decline messages — when CardPointe declines a card (expired, do not honor, call for authorization, PIN tries exceeded, and related responses), customers see a clear explanation on classic and Blocks checkout instead of WooCommerce Blocks' generic "Something went wrong" fallback. Processor
resptextstill goes to the payment logs. Developers can override the copy withwoocommerce_stitch_customer_decline_message. - Tokenizer iframe CSS — the card-number field inside the CardPointe iframe now receives height, padding, border, and color from the active style preset. CardPointe rejects the entire
cssURL parameter when it contains double quotes (for example around"Segoe UI"); font names are now unquoted so the stylesheet injects correctly.
0.5.1 — 2026-09-04
Checkout performance follow-up.
Improved
- Faster Place order — classic and Blocks checkout now ask the CardPointe tokenizer iframe immediately and retry fewer times, instead of waiting 200ms and polling for up to 3 seconds.
- Fewer surcharge requests — billing postcode changes no longer trigger a surcharge lookup on every keystroke. The lookup waits until typing pauses; leaving the field or using autofill still updates immediately.
Security
- Blocks tokenizer origin — Blocks checkout now sends tokenizer
postMessagecalls only to the CardPointe origin, matching classic checkout (no wildcard target).
0.5.0 — 2026-09-03
Guest checkout and authorize-only (capture later).
Added
- Guest checkout — shoppers can pay with a new card without logging in, on classic and Blocks checkout. Saved cards and the Save card for future purchases checkbox still require an account: guests never see stored methods, and a guest request cannot charge another customer's saved profile. WooCommerce Subscriptions still creates an account at checkout when a subscription is in the cart, so renewals are unaffected.
- Authorize only (capture later) — a new Transaction type setting under WooCommerce → Settings → Payments → Stitch → Other settings chooses Charge (authorize and capture immediately, the default) or Authorize only. In authorize-only mode the card is held, the order moves to On hold, and stock is reserved. Change the order to Processing or Completed to capture the payment, or cancel it to void the hold and release the customer. If capture fails, the order returns to On hold so you can retry after checking CardPointe. See Authorize and capture.
- Capture status on orders — authorize-only orders store
_stitch_capture_status(authorized,captured, orvoided) alongside the other payment references, and it is retained for accounting.
Changed
- Subscription renewals always charge immediately, regardless of the Transaction type setting. Card authorizations expire after several days — capture promptly.
0.4.0 — 2026-09-02
Checkout styling system: presets, accent color, custom CSS, and a live-restyling admin preview.
Added
- Checkout style presets — a new Checkout style setting in the Checkout display section switches the payment form between Default, Minimal, Compact, and Dark looks on both classic and Blocks checkout. The form stylesheet is now built on
--stitch-*CSS variables, so a theme can restyle the form by overriding variables instead of fighting selectors, and developers can register their own presets with the newwoocommerce_stitch_style_presetsfilter. The card-number field rendered inside the CardPointe iframe follows the active preset automatically. - Accent color and custom CSS — an Accent color picker overrides the preset accent (field focus outlines, the selected saved-card highlight, and the form's radio/checkbox controls), and an advanced Custom checkout CSS box appends merchant CSS after the preset on both checkout types. Custom CSS is sanitized so it cannot inject markup, and the setting links to the full variable reference.
- Live style preview — the settings-screen checkout preview now restyles instantly as you change the style preset, accent color, or custom CSS, before saving.
- Inline card brand icon — a Visa/Mastercard/Amex/Discover icon now appears inside the card number field as soon as the card is recognized, on classic and Blocks checkout. Previously a brand icon only appeared in the optional animated card preview.
- Brand fallback for saved cards — when a CardPointe response omits the card brand, saved cards now derive it from the format-preserving token (its second digit is the first digit of the real card number), so the correct logo still shows at checkout and in My Account.
Security
- API host allowlist — the test/production base URL overrides now only accept CardPointe domains (
cardconnect.com/cardpointe.com), so API credentials can never be sent to an arbitrary host through a mistyped setting. White-label hosts can be allowed via the newwoocommerce_stitch_allowed_api_hostsfilter; rejected overrides fall back to the default endpoint and log a warning. - Log redaction for raw bodies — unparseable (non-JSON) API responses are now redacted before they reach the logs, matching the redaction already applied to structured responses.
Fixed
- Card brand detection from tokens — CardSecure tokens always start with
9, so the previous first-digit matching never identified a brand from the tokenized number. The card preview icon and the Amex 4-digit CVV rule now work correctly. - Leftover Blocks-checkout order meta — the temporary
_stitch_save_payment_methodflag written by Blocks (Store API) checkout is now removed after payment, as the data retention reference already documented. The cleanup now reads the retention reference's key list directly so documentation and behavior cannot drift apart. - Untranslated strings — the card preview's "Your name" placeholder on classic checkout and the accepted-card icon titles are now translatable.
- Elementor detection cost — checkout detection now skips all Elementor page-meta lookups on sites that don't run Elementor.
- Saved Discover cards — CardPointe reports Discover as
DSCV, which the icon mapping did not recognize; those cards now display the Discover logo instead of a generic card icon. - Dark preset readability — the payment form now gets its own dark panel with light text, so field labels and saved-card details stay readable regardless of the site theme (previously the theme's dark text could sit on the preset's dark surfaces).
- Dark preset logo — the white Stitch logo variant is used automatically with the Dark preset so it remains visible; a custom logo URL still takes precedence.
Changed
- The Data retention reference in gateway settings is now collapsed behind a "View data retention reference" toggle, keeping the settings screen compact while the full summary remains one click away.
Compatibility
- Tested up to WordPress 7.1
0.3.2 — 2026-08-11
Security and payment-safety hardening, privacy-conscious logging, and a compatibility refresh.
Security
- Saved-method ownership enforcement — before charging a saved payment method, the plugin now verifies that the CardPointe profile/account pair belongs to the paying customer's own WooCommerce payment tokens. Profile identifiers supplied by the checkout request can no longer reference another customer's stored card.
- Surcharge endpoint hardening — the surcharge AJAX endpoint only resolves saved-card profiles that belong to the logged-in customer, closing a probe path for arbitrary CardPointe profile IDs.
- Credential handling — the gateway settings option (which contains API credentials) is no longer autoloaded on every request, and saved API passwords are no longer pre-filled into the settings form. Leave a password field blank to keep the current value.
- Tokenizer messaging — checkout messages to the CardPointe tokenizer iframe are sent only to the tokenizer's origin instead of a wildcard (
*) target.
Payment safety
- No more blind retries of money-moving calls — authorizations, refunds, and profile creation are attempted exactly once. Previously a request that timed out was resent automatically, which could double-charge (or double-refund) if the original request had actually reached the processor. Idempotent calls (voids, inquiries, surcharge lookups) remain retryable.
- Interrupted-authorization recovery — if an authorization fails without a usable response (timeout, dropped connection, gateway error), the plugin queries the processor by order ID and adopts the approved transaction if one exists, recording an order note. This applies to both checkout payments and subscription renewals.
- Safer refund failures — a refund interrupted before a response arrives now returns a clear admin message asking the merchant to verify the transaction at CardPointe before retrying, instead of a generic error.
Privacy
- Payment-complete log entries no longer include customer details (user ID, email, billing name, postal code) unless Enhanced Debug Logging is enabled. That setting is now functional; keep it disabled in production.
Fixed
- Saved cards bypassing the surcharge disclosure on Blocks checkout — WooCommerce Blocks rendered saved Stitch cards as separate top-level payment options above the payment method list. Paying through that native option skipped the Stitch payment form entirely, so the customer was never shown the processing-fee disclosure. Saved Stitch cards are now always selected inside the Stitch payment method, which runs the fee lookup. A new
woocommerce_stitch_hide_native_saved_methodsfilter can restore the native options. My Account → Payment methods is unaffected. - Surcharge notice for preselected saved cards — the processing-fee notice now stays visible when a customer's default saved card is preselected at checkout. Previously the checkout refresh that renders the order-total disclosure also wiped the in-form notice (and could drop the fee recorded for the order), so a customer who simply kept the default card and paid was never shown the surcharge.
Changed
- Added links to this documentation site from the plugin description, the gateway settings screen, and the readme files.
- Removed the unimplemented Webhook URL settings section — it will return when a webhook handler ships.
- The gateway is now hidden at checkout when the store currency is not USD, instead of failing with an error at payment time.
Compatibility
- Tested up to WordPress 7.0.3, WooCommerce 11.0.1, and PHP 8.5.1
- Updated plugin headers:
Tested up to: 7.0,WC tested up to: 11.0
0.3.1 — 2026-06-25
Security hardening and modern-WordPress maintenance. No change to checkout behavior.
Security
- The card security code (CVV) is no longer written to the database during WooCommerce Blocks checkout. It is now held in a request-scoped in-memory store (
Payment_Request_Store) for the duration of the authorization request and discarded immediately afterward — reducing PCI scope. The classic checkout path already passed the CVV through the same request without persisting it.
Maintenance
- Removed the manual
load_plugin_textdomain()call. The plugin requires WordPress 6.5+ and its text domain matches the slug, so translations load automatically; this also avoids the "translation loading triggered too early" notice on newer WordPress.
Quality & tooling
- Upgraded static analysis to PHPStan 2.x and reduced the ignore baseline (resolved redundant
method_exists()guards, narrowed return types, and other findings) - Expanded the unit-test suite (payment validation, auth payloads, checkout display, card icons, checkout context, CVV store) and added a WordPress + WooCommerce integration-test scaffold (all excluded from the release package)
0.3.0 — 2026-06-25
Internal architecture, developer tooling, and surcharge hardening. No change to checkout behavior.
Architecture
- Refactored the monolithic gateway into focused service classes:
Admin_Preview,Settings_Fields,Checkout_Display,Payment_Processor,Account_Payment_Methods,Subscription_Support,Surcharge_Service, andOrder_Meta_Box - The
Gatewayclass shrank from roughly 2,630 to about 1,000 lines, with each responsibility now isolated and independently testable
Surcharge
- The disclosed credit card surcharge is now derived from the server-side cart total instead of trusting the posted amount
- AJAX surcharge responses now use standard
wp_send_json_success()/wp_send_json_error()envelopes - Fixed a unit mismatch that could overstate the surcharge rate, and a case where a non-eligible card could still show a fee
Developer API
- New filter
woocommerce_stitch_register_gatewayto enable or disable gateway registration (useful for staging or conditional rollouts), replacing a hardcoded flag - Changed: checkout-presentation helpers (
get_payment_form_i18n(),get_saved_payment_methods_for_checkout(),get_checkout_display_settings(),get_iframe_css(), and related) moved fromGatewayto the newCheckout_Displayclass, accessible via$gateway->checkout_display()
Quality & tooling
- Added PHP_CodeSniffer (WordPress + WooCommerce), PHPStan, and a PHPUnit unit-test suite (all excluded from the release package)
- Sanitized admin settings-screen detection query parameters
Documentation
- Removed legacy child-theme references from code and docs
- Clarified data-retention and activation / deactivation / uninstall behavior
- Bumped tested-up-to to WordPress 6.9
0.2.0 — 2026-06-10
Admin
- Redesigned gateway settings page with branded hero, status pills, and tabbed Test / Production credentials
- Live Checkout preview panel with AJAX updates before save; sticky sidebar on desktop
- Reorganized settings: Checkout display (including card preview), Other settings (stored payments, surcharge, debug logging)
Checkout display
- Toggle Stitch logo, accepted card icons, in-form description, and card preview
- Custom checkout logo URL and field label overrides (card number, expiry, CVV, cardholder name)
- Classic template via
wc_get_templatewith theme override atwoocommerce/stitch/payment-form.php - Shared display settings and i18n for classic and Blocks checkout
Developer API
- Filters:
woocommerce_stitch_payment_form_template_args,woocommerce_stitch_saved_payment_methods,woocommerce_stitch_payment_form_i18n,woocommerce_stitch_accepted_card_brands,woocommerce_stitch_payment_header_html,woocommerce_stitch_is_checkout_context, and related checkout/asset filters - Actions:
woocommerce_stitch_before_payment_form,woocommerce_stitch_after_payment_header,woocommerce_stitch_before_new_card_fields,woocommerce_stitch_after_payment_form Checkout_Contextclass for WooCommerce checkout, add-payment-method, shortcode, and Elementor widget detection- Public gateway helpers (
get_payment_form_i18n(),get_saved_payment_methods_for_checkout(), etc.) Card_Icons::kses_payment_header_html()for SVG-safe payment header output- In-plugin guide at
docs/DEVELOPERS.md
Checkout UX
- Auto-advance focus from card number → expiry → CVV → cardholder name when each field passes validation
Packaging & i18n
package.phprelease zip builder with.distignorefor Windows-friendly packaging- Fixed
translators:comments for surcharge disclosure strings
Fixed
- Accepted card icon SVGs were stripped from the payment header by
wp_kses_post()— header output now uses a dedicated allowlist
Documentation
- Merchant and developer documentation site updated to match 0.2.0 (this site)
0.1.0 — 2026-06-05
Initial standalone plugin scaffold.
Added
- WooCommerce payment gateway (
stitch) with test and production credentials - WooCommerce dependency and activation checks
- HPOS (custom order tables) compatibility declaration
- WooCommerce Cart & Checkout Blocks compatibility
- CardPointe API client with sanitized logging paths
- Custom payment token type
WC_Payment_Token_Stitchfor saved cards - Classic checkout payment form with hosted card tokenizer
- WooCommerce Blocks payment method integration
- Payment processing and saved-token creation
- Refund and void handling with admin order transaction details
- WooCommerce Subscriptions renewal hooks and scheduled renewal processing
- Surcharge calculation, session disclosure, and order-meta persistence
- Data retention settings and uninstall policy options
Notes
This version established the migrated gateway for local and staging verification. Complete manual testing for classic checkout, Blocks checkout, saved cards, refunds, voids, subscriptions, surcharge disclosure, HPOS, and failure paths before production use.
Documentation site built by MindK for Stitch Payments.