payment-method-add

name

payment-method-add

description

Use when adding a new payment method to the Stripe gateway. Triggers include "add payment method", "new UPE method", "support <method-name> on checkout", "register a payment method", or any work that introduces a new `WC_Stripe_UPE_Payment_Method` subclass. A new method spans PHP and frontend plus constants and registration; this skill walks the full sequence so nothing is silently missing on checkout.

Add a Stripe Payment Method

Adding a payment method touches at least five places across PHP and frontend. The most common pitfall in this codebase is missing one of them — the method either doesn't appear on checkout at all, or appears on one surface but not another.

Required changes (in order)

1. PHP class

Create includes/payment-methods/class-wc-stripe-upe-payment-method-<id>.php extending WC_Stripe_UPE_Payment_Method.

Required overrides at minimum:

• get_id() — return the Stripe payment method type (e.g., klarna, affirm, sepa_debit).
• get_label() — translated method name shown to merchants in admin.
• get_icon() — return the icon URL registered in step 4.
• Capability flags — is_subscription_supported(), is_pre_order_supported(), currency/country constraints.

If the method supports recurring payments, also include WC_Stripe_Subscriptions_Trait and ensure subscription/pre-order initialization runs in the gateway constructor. Reference an existing recurring-capable method (Klarna, Card, SEPA) for the trait wiring pattern.

2. Constants

Add the method ID to includes/constants/class-wc-stripe-payment-methods.php using the existing STRIPE_<METHOD> constant convention. The constant is referenced from webhook handling, payment processing, and admin REST endpoints — leaving it out is a silent breakage.

3. Registration

Add the new class to the payment method classes array initialized in WC_Stripe::init(). The order in this array influences display order on checkout — match the design's intended position rather than appending blindly.

4. Icon

Add the icon asset under client/payment-method-icons/ (SVG preferred). Register it in client/payment-method-icons/index.js so get_icon() resolves correctly.

5. Blocks support

Add the method config under client/blocks/upe/. Blocks integration is a separate registration from classic checkout; without this entry, the method is invisible in Blocks checkout even when classic works.

Validation matrix (CRITICAL)

Per the project's CRITICAL rule, any change to payment-method availability or rendering must be validated across all four checkout surfaces. A new method must be verified on:

Surface	Where to test
Classic checkout	/checkout with Blocks disabled
Blocks checkout	/checkout with Blocks enabled (default for new sites)
Optimized Checkout (OCS)	/checkout with OCS enabled in plugin settings
Express checkout (ECE)	Verify the Apple Pay / Google Pay / Link / Amazon Pay buttons on each ECE surface: product page, cart, checkout, and pay-for-order

If the method intentionally does not support a surface, verifying that it's cleanly hidden — not erroring — is still a tested outcome.

Tests

• PHPUnit: add tests/phpunit/payment-methods/class-wc-stripe-upe-payment-method-<id>-test.php. Use @dataProvider for capability matrix scenarios (subscriptions on/off, pre-orders on/off, currency, country).
• Jest: if the Blocks config or icon registration has logic beyond static configuration, add a Jest test in a __tests__/ folder alongside the code (e.g., client/blocks/upe/__tests__/).
• E2E: at minimum one shopper happy-path spec under tests/e2e/specs/<method>/. Several methods have dedicated Playwright projects — match the existing convention rather than dropping into default.

Recurring-payment regressions

If the method supports subscriptions or pre-orders, add coverage that exercises:

• The subscription renewal path (WC_Stripe_Subscriptions_Trait::renew_subscription flow)
• The pre-order release path (WC_Stripe_Pre_Orders_Trait)
• Webhook handling for the relevant payment_intent.* and setup_intent.* events

Recurring-payment regressions are explicitly called out as a "common pitfall" in includes/AGENTS.md.

Common mistakes

• Adding the class but forgetting WC_Stripe::init() registration → method silently absent on checkout.
• Forgetting the constant in WC_Stripe_Payment_Methods → webhook handler can't classify charges; admin REST endpoints break.
• Forgetting Blocks support → method works on classic but disappears in Blocks.
• Forgetting icon registration → broken-image placeholder on checkout.
• Validating only one checkout surface → regression on the other three.
• Missing subscription/pre-order trait wiring on a recurring-capable method → renewals fall back to manual.