Stripe Integration Concepts

This document explains the key concepts behind iaptic's Stripe integration.

Core Components

1. Access Keys

Access keys are secure tokens that allow client applications to verify subscription status without exposing Stripe API keys. They:

• Are generated during checkout
• Have a 30-day expiration
• Can be rotated automatically
• Are subscription-specific

2. Entitlement Strategies

Determines how subscriptions are associated with users:

• ALL_CLAIMERS: Multiple users can share a subscription
• LAST_CLAIMER: Only the most recent user has access

3. Product Types

Three types of products supported:

• Paid Subscriptions: Recurring payments
• Consumables: One-time purchases
• Non-consumables: Permanent one-time purchases

4. Metadata

Stripe metadata is used to:

• Define product types
• Store user associations
• Control product visibility
• Configure features

Key Relationships

Subscription Ownership

graph LR
    A[Subscription] -- metadata --> B[application_username]
    B -- strategy --> C[Entitlement]
    C -- ALL_CLAIMERS --> D[Multiple Users]
    C -- LAST_CLAIMER --> E[Single User]

Access Control

graph LR
    A[Client] -- access_key --> B[API]
    B -- verify --> C[Subscription]
    C -- rotate --> D[New Access Key]
    D -- return --> A

Integration Points

1. Checkout Flow

1. Create checkout session
2. Generate access key
3. Store in subscription metadata
4. Complete payment
5. Associate with user

2. Subscription Management

1. Customer portal access
2. Plan changes
3. Payment updates
4. Cancellation

3. Webhook Processing

1. Event reception
2. Signature verification
3. Metadata processing
4. Status updates

Technical Requirements

API Version

• Stripe API version: 2024-11-20.acacia
• Required for webhook compatibility
• Ensures consistent behavior

Security Model

• Client-side: Access keys
• Server-side: API keys
• Webhook: Signing secrets

Common Patterns

User Association

// During checkout
{
  metadata: {
    application_username: 'user123'
  }
}

// After purchase
subscription.metadata.application_username

Product Configuration

// Subscription product
{
  metadata: {
    product_type: 'paid subscription',
    features: 'premium,api,support'
  }
}

// One-time purchase
{
  metadata: {
    product_type: 'consumable',
    credits: '1000'
  }
}

Access Control

// Client-side verification
const { purchases } = await iaptic.getPurchases(
  subscriptionId,
  accessKey
);

// Server-side verification
const subscription = await stripe.subscriptions.retrieve(
  subscriptionId
);

State Management

Subscription States

• Active
• Past Due
• Canceled
• Trial
• Incomplete
• Incomplete Expired

Access Key States

• Valid
• Expiring
• Expired
• Rotated

Integration Boundaries

Client Responsibility

• Store access keys
• Handle rotation
• Manage UI state
• Process errors

Server Responsibility

• Process webhooks
• Validate signatures
• Update metadata
• Track state

Iaptic Responsibility

• Generate access keys
• Validate subscriptions
• Process events
• Manage entitlements