Stripe Integration

Checkout, payment intents, webhooks, and ledger reconciliation.

Stripe handles payment processing, subscription billing, and webhook-driven event handling.

Webhook handler

typescript

export async function POST(request: Request) {
  const signature = request.headers.get("stripe-signature");
  const body = await request.text();
  const event = stripe.webhooks.constructEvent(body, signature!, secret);
  await handlePaymentEvent(event);
  return Response.json({ received: true });
}

Required webhook events

Event	Action
`payment_intent.succeeded`	Mark order as paid, trigger fulfillment
`payment_intent.failed`	Notify user, log failure reason
`customer.subscription.updated`	Sync subscription status
`invoice.payment_failed`	Send dunning email, flag account

Environment variables

dotenv

STRIPE_SECRET_KEY=sk_test_...        # From vault
STRIPE_WEBHOOK_SECRET=whsec_...      # From vault
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Testing locally

Use the Stripe CLI to forward webhooks to your local server:

bash

stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger payment_intent.succeeded

Reconciliation

Run daily reconciliation to match Stripe ledger entries with internal order records. Discrepancies are flagged for the payments team.