Where a card lives
Not here — your subscription explains who holds it. Invoices is the record, plans and pricing is what you are paying for, and refunds and lapses is what happens when a charge comes back.
At the payment rail. Never here, and never in your Worker.
The dashboard is a Pithy application, and payments is one of the capabilities it composes — so it works the way it does for you: the rail holds the instrument, and the kit holds the purchase record.
Managing it
Through the rail’s own portal, reached from the dashboard.
A portal return URL is config, not request input — a client that could name a return URL could send a paying customer to a page it controls.
What the purchase record holds
A logical product id, a rail, the rail’s own transaction id, and what it granted.
Not a card number, not a token you could charge with.
UNIQUE (rail, providerTransactionId) is the idempotency anchor, which is why a retried submission records once.
A failed payment
Grace still grants. A subscription in its billing-retry period keeps its entitlements — a failed card should not lock you out mid-period.
Once grace is exhausted it moves to on-hold, which never grants.
What we would not be able to tell you
A subscription can lapse with no notification arriving at all. A store simply stops renewing, and nothing announces it.
Which is why the kit checks expiry on read rather than trusting a stored flag — a row saying active with a date in the past does not grant, and it does not need a write to stop granting.
That is the same code path your own project uses, and it is documented at resolving entitlements.
Refunds
A refund is the rail’s, and the entitlement follows.
A clawback of anything a purchase credited is off by default — you may already have spent it, and a clawback that would overdraw is refused rather than routed around.
Invoices
See invoices.