SuperAPI AI Directory

payment-method-add

Coding & development

View repository

Updated 10-16 07:18

About this skill

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.