Skip to content

Club Card Payment

A WordPress plugin that lets parents pay for one-off items by card, via Stripe Checkout — separate from the GoCardless-based registration and instalment payments in Club Player Manager.

It is a companion to Club Player Manager, not part of it. It links an order to a player through CPM_Platform::verify_player() — the one seam it is allowed to read core's player data through — and stores everything else in its own tables, so the two can be installed, upgraded, backed up and removed independently.


What it does

  1. Products. An admin creates, edits and archives one-off items (name, description, price, currency). Archived products are kept, never deleted, so past orders still resolve to a name.
  2. Payment requests. An admin sends a guardian an emailed pay link for a specific player and product.
  3. The shop. A public shortcode where a parent identifies their child by Club Player ID + surname, then buys any active product for that player by card.
  4. Stripe Checkout handles the actual card processing. A webhook, never the browser redirect back from Checkout, is what confirms payment — the same discipline core's GoCardless integration follows for its own webhook.

Requirements

  • WordPress 6.9+, PHP 8.2+
  • Club Player Manager installed and active, at platform version 3.10 or newer
  • Composer dependency: stripe/stripe-php, Strauss-scoped into CCP\Vendor\ — see Development

Shortcodes

[ccp_shop]         Identity form (Club Player ID + surname), then a product list and "Pay by card".
[ccp_pay_request]  Resolves ?ccp_pay=<token> from an admin-sent payment-request email.

Both are unauthenticated public forms, and both follow the same anti-enumeration discipline as core's FA Number + date-of-birth lookup (class-registration-request.php): a honeypot field, a per-IP throttle on failed lookups, and — the important part — answering identically whether the details given were wrong in one way or another, so neither form can be used to enumerate valid Club Player IDs, player names, or request tokens.

Admin

Card Payments (top-level menu), all gated on the ccp_manage capability — granted to WordPress administrators and to Club Player Manager club admins (cpm_manage_all).

Screen What it is for
Products Add/edit/archive one-off items
Send Payment Request Verify a player, choose a product, email a guardian a pay link
Orders Every purchase and payment request, filterable by status; Resend email, Cancel
Settings Stripe keys and mode (test/live), currency, shop intro text, which page hosts [ccp_pay_request]

Data model

Three tables, all wp_ccp_*:

Table Holds
ccp_products One-off items: name, description, price (minor units), currency, active/archived
ccp_orders One row per purchase or payment request: product + player snapshots (survive edits/archival elsewhere), amount, status, Stripe IDs, the request token an emailed link carries
ccp_events Stripe webhook event ledger. An event id is recorded only after it is applied, so a redelivered webhook is a no-op — mirrors cpm_gc_events

Payment confirmation

Nothing in this plugin marks an order paid from a browser redirect. [ccp_shop] and [ccp_pay_request] create (or reuse) a pending/requested order, start a Stripe Checkout Session, and redirect the parent to Stripe. The success_url/cancel_url Stripe sends them back to only ever changes what the page shows — the order is marked paid exclusively by CCP_Rest::handle_webhook(), once it has verified the Stripe-Signature header, on checkout.session.completed.

Stripe sends a shop buyer back to the shop page and a request payer back to their request page (with their ccp_pay token), carrying ccp_result=success or ccp_result=cancelled. The page then shows a general "being confirmed" or "cancelled" notice and nothing about the order.

An order keeps at most one Checkout Session open. "Pay Now" reuses the order's session while it is still open for the same amount, expires it first if the amount has changed, and refuses to open another once it has been paid. Cancelling an order on the Orders screen expires its open session, so a parent still on the Stripe page cannot pay for it afterwards.

Generating test data

For a development or staging install, the wp ccp generate WP-CLI command populates the plugin with realistic demo data — a small catalogue of products (one archived) and a spread of orders across every status and both order sources. Names are drawn from a broad range of world cultures, and every guardian email address uses the reserved @example.com domain, so nothing it creates can reach a real inbox. Unlike core's generator, it does not need a real player to exist first: orders carry their own player_id/name snapshot, fabricated by the generator itself.

wp ccp generate all                                # 6 products + 20 orders
wp ccp generate all --products=10 --orders=80      # a larger dataset
wp ccp generate all --seed=42 --yes                # reproducible, no prompt
wp ccp generate reset                              # remove everything it created

Generated records are tracked by ID in the ccp_demo_data_ids option, so reset removes only demo data and leaves real records untouched. This is a dev/staging aid only — the command is registered under WP-CLI and never runs on a web request. See CCP_Test_Data_Generator.

Environment gate. Both commands refuse to run in a production environment, so they can never touch a live club's site. This is decided by WordPress's standard WP_ENVIRONMENT_TYPE (an environment variable or wp-config.php constant), which defaults to production when unset — so the generator is disabled by default until the environment is explicitly set to local, development or staging:

# In the shell, or via wp-config.php: define( 'WP_ENVIRONMENT_TYPE', 'development' );
export WP_ENVIRONMENT_TYPE=development
wp ccp generate all

# Escape hatch: force-allow on a box whose environment type is mislabelled.
CCP_ALLOW_TEST_DATA=1 wp ccp generate all

Development

Everything runs from the repository root, where the shared dev tooling lives:

composer test        # every plugin's suite
composer test:ccp    # this plugin only
composer lint        # every plugin's phpcs ruleset
composer lint:ccp    # this plugin only

composer build -- club-card-payment   # dist/club-card-payment/club-card-payment-<version>.zip

The test suites stub WordPress and run against a real SQLite database, and are never built with the vendored Stripe SDK — see .github/workflows/test.yml. Every Stripe SDK call is funnelled through CCP_Stripe's private call_stripe()/client() helpers, mirroring CPM_GoCardless's call_gc(); only the SDK-free logic (verify_webhook_signature(), implemented by hand from Stripe's documented HMAC-SHA256 scheme) has unit coverage. The SDK-calling methods themselves are deliberately untested, the same way CPM_GoCardless's SDK calls are — see .claude/skills/club-management/references/patterns.md and CCP_Stripe's class doc for why.

To actually build the plugin (not required for composer test):

cd plugins/club-card-payment
composer install
composer strauss

Layout

club-card-payment.php                 Bootstrap: constants, require order, hooks
uninstall.php                         Drops every table and option

includes/
  class-ccp-schema.php                Table definitions + the migration walk
  class-ccp-database.php              Table names + a facade over the repositories
  db/class-ccp-*-repository.php       Products, orders, the Stripe event ledger
  class-ccp-access.php                The ccp_manage capability
  class-ccp-credentials.php           Stripe secrets, encrypted at rest in ccp_credentials
  class-ccp-settings.php              Options: get(), allowlisted save() — holds no secret
  class-ccp-stripe.php                Stripe SDK wrapper + hand-rolled webhook signature check
  class-ccp-rest.php                  The Stripe webhook REST route
  class-ccp-shortcodes.php            [ccp_shop] and [ccp_pay_request]
  class-ccp-test-data-generator.php   Demo products/orders for `wp ccp generate` (dev/staging only)
  class-ccp-cli.php                   The `wp ccp generate` WP-CLI command
  admin/                              One handler per screen, plus the orchestrator

templates/                            admin-*.php, frontend-*.php
assets/css/
tests/Unit/  tests/Integration/  tests/Support/

Configuring Stripe

Test and live credentials are stored side by side, and the Mode radio decides which set is used to take payment. Stripe has no separate API host for testing — the key itself carries the environment (sk_test_… against sk_live_…) — so switching mode is the whole switch. A dev or staging site sits on Test; production sits on Live.

  1. In Card Payments → Settings, add your secret and publishable keys. Fill in both modes if you have them; only the selected mode's keys are ever used.
  2. In the Stripe Dashboard, add a webhook endpoint pointing at <site>/wp-json/ccp/v1/stripe-webhook, subscribed to checkout.session.completed, and paste its signing secret into the matching field.

Do this once per mode. Stripe issues a different signing secret for every endpoint, and a test-mode endpoint and a live-mode endpoint are two different endpoints — hence the separate Test and Live webhook signing secret fields. Getting this wrong is quiet and expensive: the card is charged, the webhook then fails signature verification, and the order sits unpaid. (Core stores its GoCardless webhook secret per environment for exactly the same reason.) 3. Create a page containing [ccp_pay_request] and select it under Payment request page — payment-request emails link here. Create a separate page (or the same one) containing [ccp_shop] for the public shop.

How the credentials are stored

The secret keys and webhook signing secrets are encrypted at rest (libsodium secretbox) in their own option, ccp_credentials, which is not autoloaded — so they are read only when something actually asks for one, and a stolen database, a staging clone or a backup yields ciphertext rather than a live key.

The four secret fields are therefore write-only. The saved value is never rendered back into the page, so the settings screen shows only a masked hint (••••1234):

  • Leave a field blank to keep what is already stored. Saving the currency cannot wipe your keys.
  • Type a new value to replace it.
  • Tick "Remove the saved value" to clear it. That checkbox is the only way to clear one; a typed value wins if you do both.

The publishable keys are public — Stripe designs them to be embedded in web pages and handed to every visitor's browser — so they are stored plainly and shown as ordinary text fields. Encrypting them would imply a secrecy they do not have.

The encryption key

The key is derived from the first of these that is available:

  1. CCP_ENCRYPTION_KEY — a constant in wp-config.php, for a site that wants this plugin's secrets on their own key.
  2. CPM_ENCRYPTION_KEY — a site-wide name reserved for this family of plugins, so that one line in wp-config.php can cover every plugin that reads it. Today only this plugin reads it. Club Player Manager itself does not use the constant, and does not encrypt its own stored credentials (its GoCardless access tokens) with it, so defining it protects this plugin's Stripe secrets and nothing else.
  3. wp_salt( 'secure_auth' ) — the fallback when neither constant is defined.

Define a constant. Add something like this to wp-config.php, above the /* That's all */ line:

define( 'CPM_ENCRYPTION_KEY', 'a long random string you keep somewhere safe' );

Relying on the salt fallback works, but WordPress salts are rotated by some hosts during a migration, and rotating the key material makes every stored credential undecryptable. That is handled rather than fatal — the settings screen says the saved value cannot be decrypted, and payments report as unconfigured instead of erroring — but it means re-entering the keys by hand.

Be honest about what this buys: wp-config.php holds both the salts and the database credentials, so an attacker who reads that file and the database gains nothing from the encryption. What it defeats is database-only compromise — backups, staging clones, migration plugins, SQL injection — which is the common case.

Locally, stripe listen --forward-to <site>/wp-json/ccp/v1/stripe-webhook prints a signing secret of its own; that is the one to paste into Test webhook signing secret while the CLI is running.