Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What 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.cycle for 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-settings

2Manually: put the files in place

.claude/rules/payment-testing.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Testing and QA →

From the same set113

The whole set →
derive-client derive-client records browser network traffic into a HAR archive and turns captured internal endpoints into a standalone API client or CLI script. CX Codex +1 ★ 1,216repo stars polar-local-environment The polar-local-environment skill for Claude Code manages Polar’s local Docker setup, including stack operations, service debugging, and separate environments for multiple worktrees. CX Codex +1 ★ 1,216repo stars yolo-training yolo-training reads YOLO26 training curves and results.csv, diagnoses overfitting or poor mAP, and points to the cheapest fix first. CX Codex +1 ★ 1,216repo stars supabase-cli Equips coding agents to run Supabase CLI commands for local environments, schema migrations, edge function deployments, and TypeScript type generation. CX Codex +1 ★ 1,216repo stars troubleshooting troubleshooting — a rule covering common failures in a Dockerized Polar dev stack, from stuck ports to stale database connections. CX Codex +1 ★ 1,216repo stars supabase-js Adds practical cheat sheets and patterns for @supabase/supabase-js to your AI coding agent, covering Auth, Storage, Edge Functions, and queries. CX Codex +1 ★ 1,216repo stars create-pr The create-pr skill checks a branch, prepares a review-ready pull request, and publishes it with gh. Use it when you want an agent to handle the PR workflow for your changes. CX Codex +1 ★ 1,216repo stars electron Drives Electron desktop apps like Slack, VS Code, Discord, Figma and Spotify over the Chrome DevTools Protocol. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open