Stripe Integration

The StripeIntegrationService integrates the Billing Service with Stripe for payment processing. It manages checkout sessions, customer portal access, payment intents, and webhook event handling for payment lifecycle events.

Checkout Session

Endpoint: POST /api/v1/billing/stripe/checkout

Creates a Stripe Checkout session for a tenant to subscribe to a plan.

curl -X POST "http://localhost:8087/api/v1/billing/stripe/checkout?tenantId=550e8400&planId=plan-pro" \
  -H "Authorization: Bearer ${TOKEN}"

Response:

{
  "sessionUrl": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Customer Portal

Endpoint: POST /api/v1/billing/stripe/portal

Creates a Stripe Customer Portal session for self-service billing management.

curl -X POST "http://localhost:8087/api/v1/billing/stripe/portal?customerId=cus_abc123" \
  -H "Authorization: Bearer ${TOKEN}"

Response:

{
  "portalUrl": "https://billing.stripe.com/p/session/..."
}

Payment Intent

Endpoint: POST /api/v1/billing/invoices/:invoiceId/payment-intent

Creates a Stripe Payment Intent for collecting payment on a specific invoice.

curl -X POST http://localhost:8087/api/v1/billing/invoices/inv-001/payment-intent \
  -H "Authorization: Bearer ${TOKEN}"

Response:

{
  "clientSecret": "pi_abc123_secret_xyz789"
}

The clientSecret is used by the frontend with Stripe.js to complete the payment.

Webhook Handler

Endpoint: POST /api/v1/billing/stripe/webhook

Receives and processes Stripe webhook events. The handler verifies the event signature using the Stripe-Signature header.

Processed Event Types

Webhook Configuration

The webhook endpoint must be registered in the Stripe dashboard. The webhook signing secret is configured via environment variable and retrieved from Kubernetes secrets:

stripe:
  webhook-secret: ${STRIPE_WEBHOOK_SECRET}
  api-key: ${STRIPE_API_KEY}

Stripe Entity References