Skip to content

Payment provider interface: make gateway choice per event type instead of Stripe-only #246

Open

Description

@shockalotti

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/stripe is 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, plus payment_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. Keep payment_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

  1. pullfrog commented on Nov 11, 2026

    @pullfrog
    Contributor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions