Stripe

​

What the processor covers

​

Why

​

Setup

1. In apps/backend/src/configuration/development.ts, set tools.paymentProcessor:
   Copy

   Ask AI

   paymentProcessor: {
     client: PaymentProcessorClientType.STRIPE,
     apiVersion: process.env.STRIPE_API_VERSION ?? '2026-01-28.clover',
     publishableKey: process.env.STRIPE_PUBLISHABLE_KEY,
     secretKey: process.env.STRIPE_SECRET_KEY,
     webhookSigningSecret: process.env.STRIPE_WEBHOOK_SECRET,
     settings: {
       quantityDowngradePolicy: QuantityDowngradePolicy.IMMEDIATELY_PRORATED,
     },
   }
   
2. In production.ts, use QuantityDowngradePolicy.END_OF_BILLING_CYCLE unless you have a specific reason for immediate proration.
3. In your environment, set:
   Copy

   Ask AI

   STRIPE_API_VERSION=2026-01-28.clover
   STRIPE_PUBLISHABLE_KEY=pk_live_...
   STRIPE_SECRET_KEY=sk_live_...
   STRIPE_WEBHOOK_SECRET=whsec_...
   
4. For local webhook testing, use the Stripe CLI to forward events:
   Copy

   Ask AI

   stripe listen --forward-to http://localhost:4000/stripe/webhook
   
5. Run make test module=backend.

​

Quantity downgrade policy

settings: {
  quantityDowngradePolicy: QuantityDowngradePolicy.END_OF_BILLING_CYCLE,
}

​

Testing with stripeMock

paymentProcessor: {
  client: PaymentProcessorClientType.STRIPE_MOCK,
}

jest
  .spyOn(tools.paymentProcessor, "createSubscription")
  .mockResolvedValue({ success: true, result: mockSubscription });

​

Adding a new Stripe operation

1. Create apps/backend/src/tools/paymentProcessor/stripe/<operationName>.ts. Export a function that takes (stripe: Stripe, params, tools: ToolsType) and returns { success: true, result } or { success: false, reason }.
2. Add the function to the StripePaymentProcessorType interface in apps/backend/src/tools/paymentProcessor/stripe/types.ts.
3. Register it in buildStripePaymentProcessor inside apps/backend/src/tools/paymentProcessor/stripe/index.ts.
4. Add a no-op stub to createTestStripePaymentProcessor in the same file.
5. Write a test in apps/backend/src/tools/paymentProcessor/__tests__/stripe/<operationName>.spec.ts.
6. Run make test module=backend.

​

Webhooks

1. Stripe POSTs to /stripe/webhook with a Stripe-Signature header.
2. The router calls Stripe.webhooks.constructEvent to verify the signature using webhookSigningSecret. If verification fails, it returns 400 immediately.
3. The router checks whether the event type is in HandledStripeWebhookEvent (defined in apps/backend/src/utilities/stripe.ts). Unhandled event types get a 200 response and are silently ignored — this is intentional, since Stripe sends many event types you may not care about.
4. The router checks hasWebhookEventBeenProcessed to deduplicate — Stripe can deliver the same event more than once.
5. The router validates the payload shape using Zod schemas in webhookValidators.ts. This is a safety net: if Stripe changes their payload format, this fails loudly rather than letting malformed data reach your business logic.
6. The event is serialised and enqueued to QueueName.STRIPE_WEBHOOK.
7. The stripeWebhookConsumer picks it up from the queue and dispatches to the right handler based on event.type.

​

Adding a new event handler

1. Add the new event type to HandledStripeWebhookEvent in apps/backend/src/utilities/stripe.ts:
   Copy

   Ask AI

   export enum HandledStripeWebhookEvent {
     // ...existing events...
     InvoicePaymentSucceeded = 'invoice.payment_succeeded',
   }
   
2. Add a Zod validator for the payload shape in apps/backend/src/tools/queue/consumers/stripeWebhookConsumer/webhookValidators.ts.
3. Create the handler file apps/backend/src/tools/queue/consumers/stripeWebhookConsumer/invoicePaymentSucceeded.ts:
   Copy

   Ask AI

   import { ToolsType } from '../../../../tools';
   
   export const handleInvoicePaymentSucceeded = async (
     payload: YourValidatedPayloadType,
     tools: ToolsType,
   ) => {
     // business logic here
   };
   
4. Register the handler in apps/backend/src/tools/queue/consumers/stripeWebhookConsumer/index.ts.
5. Write a test in apps/backend/src/tools/queue/consumers/stripeWebhookConsumer/__tests__/.
6. For local testing, forward events using the Stripe CLI:
   Copy

   Ask AI

   stripe listen --forward-to http://localhost:4000/stripe/webhook
   # then trigger a test event:
   stripe trigger invoice.payment_succeeded
   
7. Verify:
   Copy

   Ask AI

   make test module=backend
   

​

Gotchas

• The Stripe client is configured with maxNetworkRetries: 3 and timeout: 80000ms. Operations that exceed this timeout will throw — wrap long-running calls with expRetries using isConnectionTimeoutError as the shouldRetry guard.
• Webhook signatures expire quickly. Never replay a webhook event after the tolerance window — Stripe will reject the signature.
• Never log secretKey or webhookSigningSecret — they are credentials.
• apiVersion must exactly match a supported Stripe API version string. A mismatch causes a startup error.

​

What’s next?

• Billing architecture — how Stripe fits into the broader billing system.
• Configuration — environment-level config.