payment-testing — Claude Code rule for payment tests
The payment-testing rule explains local checks for login, Stripe events, subscription renewals, refunds, and the backoffice. Use it when a payment flow behaves differently in your local stack.
Apache-2.0 ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat payment-testing does
The rule covers local authentication and payment checks: finding a login code, starting the Stripe listener, and choosing an email address for checkout. The test account is [email protected]; its login code appears in the API container logs. Run dev stripe --listen to forward events to the regular webhook and the Stripe Connect endpoint.
For a subscription renewal, the instructions show how to enqueue subscription.cycle from the API container. Importing polar.tasks registers the actors, while JobQueueManager.open(...) flushes the queued message to Redis. Both steps matter: without the import, the actor is unknown; without the queue manager context, enqueueing fails.
Local testing uses a personal Stripe sandbox. dev rejects live keys and shared team accounts, so check the profile before debugging webhook delivery. Checkout also rejects .local and example.com email domains. The backoffice shares the dashboard session, and its balance can be cross-checked against the database.
What it helps with
- find the login code in API container logs
- check whether Stripe events reach the local webhook
- enqueue a subscription renewal manually
- test checkout tax behavior
- verify balances and transactions in the backoffice
Example prompts for the agent
- Show me where to find the login code and how to use the local test account.
- Help me check Stripe webhook delivery locally and diagnose a missing event.
- How can I enqueue
subscription.cyclefor this subscription and verify the result?
How to install payment-testing
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settings2Manually: put the files in place
.claude/rules/payment-testing.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/payment-testing.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/payment-testing.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/payment-testing.mdManually: put the files in place
.clinerules/payment-testing.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about payment-testing
How do I install payment-testing in Claude Code?
Add the marketplace with /plugin marketplace add fcakyon/claude-codex-settings, then install the plugin with /plugin install polar-skills@claude-settings. The rule file is .claude/rules/payment-testing.md.
What does payment-testing do?
It documents local testing for login, Stripe webhooks, checkout taxes, and subscription jobs. It also explains how to inspect account state in the backoffice and verify balances in the database.
Which Stripe account should I use for local tests?
Use a personal Stripe test sandbox. dev rejects live keys and shared team accounts; start the listener with dev stripe --listen.
Source text
payment-testing.md · Apache-2.0
--- title: Testing Auth and Payment Flows Locally category: Operations tags: stripe, dramatiq, auth, backoffice, checkout --- # Testing Auth and Payment Flows Locally Most non-trivial bug reports against the local stack touch one of: login, Stripe webhooks, subscription renewals, refunds, or the backoffice. These all have small environmental quirks that aren't obvious from the source — this rule collects them in one place. ## Logging In Email login codes are printed in the api container logs as a banner: ``` ╔══════════════════════════════════════════════════════════╗ ║ 🔑 LOGIN CODE: ABCDE1 ║ ╚══════════════════════════════════════════════════════════╝ ``` Grab the latest one: ```bash docker logs --since 30s polar-app-<N>-api-1 2>&1 | grep -A1 "LOGIN CODE" ``` Use `[email protected]` as the default test account — the seed creates it with an approved org (`admin-org`) that already has a payout account, identity verification, and at least one product. That lets you go straight to checkout testing without onboarding work. ## Stripe Sandbox and Webhooks ```bash dev stripe --listen # or, for a non-default instance, pass the API port from `dev docker ports`: dev stripe --listen --port <api-port> ``` Local environments always run against a **personal Stripe sandbox** — never a live account, and never a shared team account. `dev` refuses both with one structural check: the linked profile must hold test keys, and since a sandbox has no live mode at all, the Stripe CLI must have stored no live key for it. A shared team account is a live account, so it fails that check. The Stripe CLI profile is always named `polar-sandbox`, so `dev` never depends on whichever account the CLI happens to have active. Pass `-p polar-sandbox` when running `stripe` by hand. `dev stripe --listen` handles the full setup in one step: installs the Stripe CLI if missing, walks through creating/linking a sandbox, writes `POLAR_STRIPE_SECRET_KEY`, `POLAR_STRIPE_PUBLISHABLE_KEY`, and `POLAR_STRIPE_WEBHOOK_SECRET` into the central secrets file, runs `dev/setup-environment` to propagate them, and then starts `stripe listen` forwarding to both the regular webhook endpoint and the Stripe Connect endpoint (`/v1/integrations/stripe/webhook` and `/v1/integrations/stripe/webhook-connect`). Re-running it later just starts the listener. `dev stripe --relink` switches to a different sandbox. Stripe CLI keys expire after 90 days. An expired key shows up as `The API key provided has expired` — `dev stripe` detects it and re-runs the link flow. `--port` defaults to `8000`. Multi-instance setups land outside the 0–2 base-port table, so read the api port from `dev docker ports` rather than computing it. Leave it running and `stripe listen` will log each event with the API's 2xx response. Missing webhook → confirm the api port matches `dev docker ports`. One listener signs both endpoints, so `POLAR_STRIPE_WEBHOOK_SECRET` and `POLAR_STRIPE_CONNECT_WEBHOOK_SECRET` hold the same value. If they already differ, they came from dashboard endpoints and `dev stripe` leaves them alone. ## Taxes `dev stripe` reports on Stripe Tax, because checkout can't price an order without it: - **inactive/pending** — checkout fails with a tax calculation error. Activate Stripe Tax in the sandbox (it needs a head office address). - **active, no registrations** — checkout works, every order is taxed at 0. - **active with registrations** — the countries are listed. To test real tax, add a registration under Tax > Registrations in the sandbox: pick "I've already registered", then "Non-Union One-Stop Shop (OSS)" for Ireland, starting immediately. EU countries then get VAT (Ireland 23%, Sweden 25%, and so on). Tax applies per the customer's billing country, so a US-only registration leaves EU orders at 0. ## Checkout Email Validation The checkout form rejects email addresses whose domain looks fake. Two common gotchas: - `.local` TLDs fail with "reserved name that cannot be used with email" - `example.com` fails with "domain does not accept email" Use a real domain with a `+tag` to keep tests isolated: `[email protected]`. ## Triggering Dramatiq Actors Manually Some flows (notably subscription renewals) are driven by background jobs that normally fire on a schedule. To force one immediately, enqueue the actor from inside the api container: ```bash docker exec polar-app-<N>-api-1 sh -c 'cd /app/server && uv run python -c " import asyncio, dramatiq import polar.tasks # registers every actor as a side-effect of import from polar.worker import JobQueueManager, enqueue_job from polar.redis import create_redis async def main(): redis = create_redis(\"worker\") async with JobQueueManager.open(dramatiq.get_broker(), redis): enqueue_job(\"<actor.name>\", *args) asyncio.run(main()) "' ``` Two non-obvious bits: - `import polar.tasks` is required. Without it, the broker has no registered actors and `enqueue_job` raises `dramatiq.errors.ActorNotFound`. - The `JobQueueManager.open(...)` context manager is what flushes the queued message to Redis. Without it, `enqueue_job` raises `LookupError` on the `polar.job_queue_manager` context var. ### Useful actors | Actor | Args | Notes | |-------|------|-------| | `subscription.cycle` | `subscription_id, force` | Advances one period. `force=True` ignores `current_period_end` — use it to fake renewals or to drive `cancel_at_period_end` subscriptions to their final cancel. | ## Inspecting the Backoffice The backoffice is mounted at `http://localhost:<api-port>/backoffice/` and uses the same session cookie as the dashboard, so logging into the dashboard also authenticates you here. Useful for verifying merchant-side state (balance, review status, transactions, audit logs) without writing SQL. A direct DB cross-check is still cheap and worth running when investigating balance/transaction issues: ```bash dev docker exec db psql -U polar -d polar_dev_<N> -c \ "SELECT total_balance FROM organizations WHERE slug='admin-org';" ```
© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings