Repository navigation
Description
From discussion #224 (kpalang, Java dev, tied to a local payment gateway with a Stripe-like redirect-and-callback flow).
Goal: let a self-hoster use a payment gateway other than Stripe, without a plugin system. Providers live in-source as thin clients. One is selectable per event type, configured site-wide by the admin.
Current state
internal/stripeis a minimal REST client:CreateCheckoutSession,VerifyWebhook,GetCheckoutSession,Refund. No Connect logic, one account per instance.- Credentials are singleton columns on
server_settings:stripe_secret_key_enc,stripe_publishable_key,stripe_webhook_secret_enc. - Bookings carry Stripe-shaped columns:
stripe_session_id,stripe_payment_intent_id, pluspayment_status. - Lifecycle hangs off one endpoint,
POST /v1/stripe/webhook->confirmPaidBooking/releaseUnpaidHold/refundBookingPayment. event_types.price_cents+currency; there is no provider choice per event type.
Staged plan
Step 1 - seam only, no behaviour change (this issue's first slice)
- Define the provider interface:
CreateCheckout,VerifyWebhook,GetSession,Refund, plus a capability flag for refunds. - Stripe becomes the sole implementation behind it.
- Rename booking columns to provider-neutral names (
payment_provider,payment_session_id,payment_ref), migrating existing Stripe values. Keeppayment_status. - No user-visible change. This is the slice that makes everything else possible and is worth doing on its own.
Step 2 - per-provider credential storage, instance default as fallback. Respect the existing precedence decision (#238/#239): DB settings beat env vars deliberately.
Step 3 - per-event-type provider selection, defaulting to the instance default. The booking must record which provider it actually used; refunds depend on it, not just reporting.
Step 4 - second implementation, gated on a real provider and a test account. A seam with one implementation behind it is untested.
Design traps to settle in step 1
- Money representation. Stripe uses integer minor units. Gateways vary: decimal strings, and currencies that are not two-decimal. Decide the boundary representation once, in the interface, not per provider.
- Refunds. Not every gateway offers an API refund. The interface must express "cannot refund" rather than promising a button that fails.
- Webhook verification is the trust boundary and differs per provider. Likely one endpoint per provider, each with replay-safe idempotency: a replayed webhook must not double-confirm a booking.
- Security surface. Each provider adds permanent attack surface. Do not add providers speculatively.
Open question
Which gateway? kpalang has a real one and a test account, which would make step 4 real rather than theoretical. Ask before starting step 4.
Discussion: #224
Activity
pullfrog commentedon Nov 11, 2026
feat(payments): extract a provider seam and neutralise the payment co…
Merge pull request #250 from Calnode/feat/payment-provider-seam