Payment Providers

Payment configuration controls checkout, renewals, refunds, and wallet credits. Use the steps below to get a stable path in production.

Provider Options

• Stripe: direct PSP. Best if you already operate your own legal entity and want full control.
• Creem (MoR): Merchant of Record handles taxes/compliance, good for global sales with less ops overhead.

Minimum Required Variables

Stripe:

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET

Creem:

• CREEM_API_KEY
• CREEM_WEBHOOK_SECRET

Optional:

• PAYMENT_PROVIDER_DEFAULT (defaults to stripe; set to creem if you want Creem as fallback)

Supported Product Types

• One-time payments: pay once to unlock delivery or entitlements.
• Subscriptions: monthly/yearly recurring billing for ongoing services and credit refresh.

Subscription Trial Period

Use trialDays on subscription products:

• trialDays > 0: subscription starts with a trial period, then transitions to normal billing.
• trialDays = 0: no trial; billing starts immediately.

Trial periods only apply to subscriptions, not one-time purchases.

Common Enablement Steps

1. Set the provider env variables.
2. In Admin → Products → Payment configs, add a config per product:
   • provider: stripe or creem
   • externalPriceId: provider-specific price/product ID
   • isActive: true
   • sortOrder: lower means higher priority
3. Restart web + API.
4. Configure the provider webhook endpoint.

Quick Setup: Stripe

1. Create products and prices

Use one Stripe product per plan, and create two recurring prices under it:

• Monthly price: recurring.interval = month
• Yearly price: recurring.interval = year

Use a globally unique lookup_key for each price.

2. Map price references

Set externalPriceId to either:

• price_xxx (direct price ID), or
• creator_monthly / lookup:creator_monthly (lookup key reference)

3. Configure webhook

Endpoint:

https://your-domain/api/v1/webhook/stripe

Recommended events:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• payment_intent.succeeded
• payment_intent.payment_failed
• payment_intent.canceled

Quick Setup: Creem

1. Create products in Creem

Each plan/credit pack should have a Creem product_id.

2. Map product IDs

Set externalPriceId to the Creem product_id for that product.

3. Configure webhook

Endpoint:

https://your-domain/api/v1/webhook/creem

Creem sends the signature in the creem-signature header (HMAC-SHA256).

Recommended events:

• checkout.completed
• subscription.active
• subscription.paid
• subscription.canceled
• subscription.scheduled_cancel
• refund.created

Buyer Checklist

1. Product payment configs match your provider catalog.
2. Webhook endpoint is reachable from the provider in production.
3. Renewal, failure, cancellation, and refund flows are tested.
4. Dashboard and admin pages show consistent order/subscription status.

Next Steps