Payments reference

Config options

Using Payments is the same ground with the code you write around it.

OptionDefaultMeaning
billingSubjectnoneuser or organization. The one answer only you can give — it lands in a column and a unique index
basePath/paymentsWhere the routes mount, webhooks included
entitlements{}Each key declared once: name, quotas, features, and an optional overrideMax. Every key a product grants must be declared here, and a declared key no product sells is comp-only
defaultsnoneThe quotas and features a caller holding no key gets
meters{}Which kit meters enforce their quota: emails, storageBytes, mediaItems. Advisory until named
graceGrantsAccesstrueWhether a subscription in billing-retry grace still grants
rails—Which rails are on
products—The catalog. A product may carry a billing block to be billed by a reported quantity

Two options ride on payments(...) beside the config, because a function does not survive the trip into config: resolveSubject, which answers who the caller acts for under organization billing, and resolveQuantity, which answers how many for a product billed by a reported quantity. A reported product with no resolveQuantity is refused at boot.

manualEntitlements is removed. A config still passing it is refused, with the declaration to write instead. Tiers, quotas and features and bill by a count you own have the shapes.

A rail that is on must declare its return URLs, and a return-URL block for a rail that is off is refused. Both checked at config rather than at the first checkout.

The rails

Standing any of them up is pithy payments; the overview is what the capability is for.

RailMerchant of record
appleNo
googleNo
stripeNo
lemonSqueezyYes
paddleYes

Nothing downstream of a rail’s own module branches on a store’s vocabulary. Every one arrives as a normalized rail-and-transaction-id pair, which is what lets one projection serve five stores.

The merchant-of-record difference is commercial rather than technical, and the only place it shows is that a refund can arrive with no local write preceding it — both issue them on their own.

The nine statuses

Each answers two questions independently.

StatusGrantsMoney arrived
activeYesYes
in_graceBy policyNo
on_holdNoNo
canceledYesYes
expiredNoYes
never_paidNoNo
refundedNoNo
revokedNoNo
pausedNoYes

expired and never_paid are the pair to read twice. Both are over, neither grants, and they differ on the only question a balance cares about — reading a never-paid purchase as expired credits a coin pack for money that never arrived, with no clawback ever to follow.

Apple maps nothing to never_paid: no transaction is issued until the money moves.

in_grace carries a date, and the paid period’s end is not it — by the time a store says grace, the period has already ended. One rail reports the window separately and the later of the two is carried; reading the transaction alone would record a grace period and revoke the subscriber in the same commit.

paused carries a resume date — the instant the store said, never one computed here. Null means the store put no end on it, so paused until the 1st and paused indefinitely stay different sentences. A row that is not paused can never carry the field — a constraint enforces it.

Routes

RoutePurposeVerification
POST /payments/purchasesSubmit a receipt or signed transactionbearer · session
GET /payments/entitlementsThe caller’s own resolved entitlements, quotas and featuresbearer · session
POST /payments/restoreRebind store history to the callerbearer · session
GET /payments/pricingWhat the caller’s subscription pays, and when it changesbearer · session
POST /payments/checkoutCreate a checkoutbearer · session
GET /payments/checkout/resumePaddle only. What a page needs to open the transaction a _ptxn payment link arrived fornone
POST /payments/portalA billing-portal session for the caller’s own accountbearer · session
GET /payments/subscriptionWhere the caller’s own subscription stands, read live from the store, with the last reported count for a product billed by quantitybearer · session
POST /payments/subscription/previewWhat moving to one catalog product would costbearer · session
POST /payments/subscription/changeMove the caller’s own subscription onto one catalog productbearer · session
POST /payments/subscription/cancelStop it renewing, today or at the end of the paid periodbearer · session
POST /payments/subscription/keepWithdraw a scheduled cancellationbearer · session
POST /payments/subscription/refundAsk the store to refund the payments made on itbearer · session
POST /payments/webhooks/<rail>One per railsigned-webhook

One public route, and it is the resume read. A buyer following a Paddle dunning mail is usually signed out, so GET /payments/checkout/resume takes no session. It discloses nothing: the client token is publishable, the display mode and success URL are config, and the transaction id is the caller’s own. It never asks Paddle whether that transaction exists. In hosted mode it refuses with payments/rail_not_configured. Every other caller is either an authenticated person acting for a subject, or a machine proving authenticity. Turnstile has nothing to gate here.

signed-webhook is one strategy over unrelated mechanisms — a signed payload against a pinned certificate chain, a token verified against published keys with an audience check, a keyed signature inside a timestamp tolerance. Each covers the exact received bytes, which is why these are literal paths per rail rather than one parameterized route: a single route line could not carry several verifiers, and the rail a caller claims is not something to route on.

Control-plane routes

RouteScope
POST /payments/admin/discountspayments:discounts:create
GET /payments/admin/discountspayments:discounts:read
POST /payments/entitlements/grantpayments:entitlements:grant
POST /payments/entitlements/revokepayments:entitlements:revoke
POST /payments/entitlements/overridespayments:overrides:set
POST /payments/entitlements/overrides/unrestrictedpayments:overrides:unrestricted
POST /payments/entitlements/overrides/clearpayments:overrides:clear
GET /payments/admin/catalogpayments:catalog:read
GET /payments/admin/purchasespayments:purchases:read
GET /payments/admin/subscriptionspayments:subscriptions:read
GET /payments/admin/entitlementspayments:entitlements:read
GET /payments/admin/entitlements/:subjectType/:subjectIdpayments:entitlements:read
GET /payments/admin/overridespayments:entitlements:read
GET /payments/admin/usage-runspayments:usage:read
GET /payments/admin/webhook-eventspayments:webhooks:read
GET /payments/admin/reconcile-runspayments:reconcile:read
POST /payments/admin/reconcile-runspayments:reconcile:run

The purchase log and the reconciliation log narrow on the server. GET /payments/admin/purchases takes the subject, rail, status, environment and type: recurring for a subscription, one_time for a consumable or a non-consumable. GET /payments/admin/reconcile-runs takes rail, environment and outcome: failed when a store refused to answer for at least one purchase, drifted when none failed and at least one was repaired, clean for neither. A pass that drifted and failed reads failed. Both page on the cursor they already had, and a value outside those is refused rather than ignored.

payments:overrides:unrestricted is its own scope because it is the largest grant the kit has: every quota unlimited and every feature on, for every name declared now or later. A credential that may raise one customer’s email cap cannot, by that fact, hand anybody the whole product.

GET /payments/admin/webhook-events is the read that explains the others. Every notification a store sent, newest received first, filtered by rail, state and a since/until window. Each reads as projected, pending with its attempts, or abandoned, so a notification that arrived and never projected shows up as exactly that rather than going missing. A projected one names the purchase and subscription rows it changed as targets; one projected before the Worker recorded them reads targets: null, which means unrecorded, not changed nothing. The payload never crosses, and a stored error crosses as its code alone. It is its own scope because the log is a record of every customer’s commerce as the stores reported it.

The package README’s route table is held to every route this capability registers by a test, which parses it and compares it against the real registrations in both directions. These tables follow that one.

That gate exists because the management reads shipped without rows for long enough that the next person to add one withheld theirs too: a table missing several peers reads as complete, so one more row would have read as a lie.

Tables

pithy_payments_purchases · pithy_payments_entitlements · pithy_payments_provider_accounts · pithy_payments_webhook_events · pithy_payments_reconcile_runs · pithy_payments_sync_cursors · pithy_payments_overrides · pithy_payments_meter_counters · pithy_payments_usage_reports · pithy_payments_usage_runs

pithy_payments_purchases also carries quantity: how many were bought, as the store states it, or null where it does not say.

Bindings

BindingTypeWritten by
DBd1pithy add
PAYMENTS_RECONCILEworkflow, optionalpithy payments provision
PAYMENTS_USAGEworkflow, only for a product billed by a reported quantityYou, with the class exported from your own entry

The Workflow binding is optional. An unprovisioned project still verifies receipts, accepts webhooks and resolves entitlements — it simply has no nightly pass.

Secrets

One: payments-provider-credentials, with a block per rail.

A rail’s block is present in full or absent entirely, checked before the write lands — so half a credential is a refusal in your terminal rather than a signature check that silently never passes.

Rotation is manual for all of them, because none of the five returns a replacement over an API.

Sandbox isolation

Every purchase carries its store environment, and a mismatch is refused outright.

The environment is an input from this deployment’s own variable and is never inferred from the payload — inferring it from what the store said is exactly the hole.

Only a Worker deployed to production is production. The asymmetry is deliberate: treating production as sandbox loses a purchase reconciliation repairs; the other way round hands out entitlements for test transactions.

Peer capabilities

Required: secrets.

Optional: auth (strongly implied — every route but the Paddle resume read denies without it), controlplane, ledger.

ESC