wire-a-new-payment-provider

Wire a new payment provider

Payments in this repo go through one adapter interface in @stack/payment. Apps and @stack/api call the interface, never a provider SDK. Swapping or adding a provider means writing a new implementation of that interface — nothing upstream changes. That's the entire reason the adapter exists.

When to use

• Replacing the default Creem adapter with Stripe/Paddle/Lemon Squeezy/etc.
• Supporting a second provider (e.g. Creem as Merchant-of-Record + Stripe for a region).
• Not for changing checkout copy or the button — that's app-side and touches no payment code.

The invariant

apps/web ──▶ @stack/api  /checkout ──▶ @stack/payment (interface) ──▶ <provider impl>
                                            ▲ everything left of here NEVER changes

If your change edits an app or an API route to call a provider SDK directly, stop — you've broken the adapter. Route it through the interface.

The interface (shape to conform to)

@stack/payment exposes a single door. Every provider implements the same contract:

export interface PaymentProvider {
  createCheckout(input: {
    priceId: string;
    customerEmail?: string;
    successUrl: string;
    cancelUrl: string;
    metadata?: Record<string, string>;
  }): Promise<{ checkoutUrl: string; sessionId: string }>;

  // Verify the signature, then return a normalized event. Throw on bad signature.
  verifyWebhook(rawBody: string, signature: string): Promise<PaymentEvent>;
}

export type PaymentEvent =
  | {
      type: "checkout.completed";
      sessionId: string;
      customerEmail?: string;
      metadata?: Record<string, string>;
    }
  | { type: "subscription.updated"; customerId: string; status: string }
  | { type: "unknown"; raw: unknown };

Steps

1. Add the impl in services/payment/src/providers/<provider>.ts, implementing PaymentProvider. Keep the provider SDK import confined to this file.

2. Config, not hardcoding. Read keys/secrets from env. Add them to .env.example with empty values and a comment: