Skip to content

Stripe Integration

The Stripe integration is a critical component of our payment infrastructure that handles all subscription management, customer lifecycle, and payment processing. This integration is primarily managed through the Admin API, which receives and processes Stripe webhooks.

System Architecture

sequenceDiagram participant C as Client participant M as Marketing Site participant S as Stripe participant A as Admin API participant DB as Database participant Cog as Cognito C->>M: Visit Landing Page M-->>C: Display Stripe Payment Links C->>S: Select Plan & Complete Payment S->>A: Webhook (checkout.session.completed) A->>DB: Create/Update Customer A->>Cog: Create User Account A-->>C: Access Granted

Key Components

1. Subscription Management

The system handles the complete subscription lifecycle:

  • New Subscriptions

    • Processing completed checkout sessions
    • Payment verification
    • Customer record creation/updates
    • Trial period management
    • Subscription expiry tracking

  • Subscription Updates

    • Plan changes (upgrades/downgrades)
    • Renewal processing
    • Contract period updates
    • Cancellation handling

2. Webhook Processing

The Admin API processes the following Stripe events:

Event Type Description Actions
checkout.session.completed Payment completion - Create customer records
- Setup subscription
- Initialize trial if applicable
customer.subscription.updated Subscription changes - Update plan details
- Process renewals
- Handle upgrades/downgrades
customer.subscription.deleted Subscription cancellation - Update contract expiry
- Handle access revocation
- Archive customer data

3. Security Measures

  • Webhook signature verification
  • Payment status validation
  • Secure customer data handling
  • Protected API endpoints

Integration Flow

1. Initial Subscription

  1. Client visits marketing/landing page
  2. Client selects a plan through Stripe Payment Links
  3. Client completes payment directly on Stripe
  4. Stripe sends webhook to Admin API
  5. System:
    • Creates/updates customer record
    • Sets up Cognito user
    • Initializes subscription

2. Subscription Updates

  1. Client requests plan change
  2. System updates Stripe subscription
  3. Stripe sends update webhook
  4. System processes changes:
    • Updates contract details
    • Modifies access levels
    • Adjusts billing cycle

Error Handling

The system implements comprehensive error handling:

graph TD A[Webhook Received] -->|Verify| B{Signature Valid?} B -->|No| C[Log Error & Return 401] B -->|Yes| D{Process Event} D -->|Success| E[Update Database] D -->|Failure| F[Log Error & Should Alert Admin]
  • Signature verification failures are logged and return a 401 status.
  • Processing failures are logged and trigger alerts for administrative review.
  • All error scenarios maintain an audit trail for traceability.

Error Scenarios

  1. Invalid Webhook Signature

    • Log security warning
    • Return 401 status
    • Alert monitoring system

  2. Database Update Failure

    • Implement retry mechanism
    • Log transaction details
    • Maintain audit trail

  3. Stripe API Issues

    • Circuit breaker implementation
    • Fallback procedures
    • Customer notification

Monitoring and Logging

  • Detailed event logging
  • Transaction tracking
  • Error reporting
  • Performance metrics

Development Guidelines

Local Testing

  1. Use Stripe CLI for webhook testing: bash stripe listen --forward-to localhost:8000/webhook

  2. Test different webhook events: bash stripe trigger checkout.session.completed

Production Considerations

  1. Webhook Security

    • Use production webhook signing keys
    • Implement retry logic
    • Monitor webhook health

  2. Error Handling

    • Log all webhook events
    • Implement proper error codes
    • Maintain audit trails

  3. Monitoring

    • Set up alerts for failures
    • Monitor webhook latency
    • Track successful transactions