Payment Method Add
Apps & Automationpayment-method-addPayment Method Add is an Agent Skill for apps & automation published in the woocommerce/woocommerce-gateway-stripe repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/woocommerce/woocommerce-gateway-stripe/blob/HEAD/.claude/skills/payment-method-add/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/payment-method-add, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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@dataProviderfor 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 intodefault.
Recurring-payment regressions
If the method supports subscriptions or pre-orders, add coverage that exercises:
- The subscription renewal path (
WC_Stripe_Subscriptions_Trait::renew_subscriptionflow) - The pre-order release path (
WC_Stripe_Pre_Orders_Trait) - Webhook handling for the relevant
payment_intent.*andsetup_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.