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¶
- 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.
- Payment requests. An admin sends a guardian an emailed pay link for a specific player and product.
- 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.
- 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 intoCCP\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):
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.
- 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.
- In the Stripe Dashboard, add a webhook endpoint pointing at
<site>/wp-json/ccp/v1/stripe-webhook, subscribed tocheckout.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:
CCP_ENCRYPTION_KEY— a constant inwp-config.php, for a site that wants this plugin's secrets on their own key.CPM_ENCRYPTION_KEY— a site-wide name reserved for this family of plugins, so that one line inwp-config.phpcan 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.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:
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.