Payment System Overview

The NEXTY.DEV payment system is a fully-featured SaaS payment solution that supports multiple payment providers. It supports both Stripe and Creem payment providers, offering complete functionality from pricing plan management, payment processing, and subscription management to a credit system.

Core Features

1. Multiple Payment Provider Support

Stripe: Globally popular payment service provider
Creem: Emerging payment service provider
Unified Interface: Handles payment logic from different providers through a unified code interface

2. Flexible Pricing Plans

One-time Payment
Subscription Payment
- Monthly subscriptions
- Yearly subscriptions

3. Complete Payment Flow

Payment session creation
Payment verification
Webhook handling
Order management
Subscription synchronization

4. Credit System

One-time credits
Subscription credits
Credit usage records
Credit balance management

System Architecture

Database Table Structure

1. `pricing_plans` - Pricing Plans Table

Stores information for all pricing plans, including:

Basic Information: id, cardTitle, cardDescription
Payment Provider Configuration: provider, stripePriceId, creemProductId
Payment Type: paymentType
- one_time (Stripe)
- onetime (Creem)
- recurring (Stripe and Creem)
Subscription Interval: recurringInterval
- month (Stripe)
- year (Stripe)
- every-month (Creem)
- every-year (Creem)
- once (Creem)
Pricing Information: price, currency, displayPrice, originalPrice
Coupons: stripeCouponId, creemDiscountCode
Multi-language Support: langJsonb (stores multi-language content in JSONB format)
Benefits Configuration: benefitsJsonb (stores benefit information in JSONB format, such as credit amounts)
Display Settings: isActive, isHighlighted, displayOrder

2. `orders` - Orders Table

Stores all payment order records:

User Association: userId
Payment Provider: provider (stripe/creem)
Order Type: orderType
- one_time_purchase (Stripe)
- onetime_purchase (Creem)
- subscription_initial (Stripe)
- subscription_renewal (Stripe)
- recurring (Stripe and Creem)
- refund (Stripe and Creem)
Order Status: status (succeeded/pending/failed/refunded/partially_refunded)
Amount Information: amountSubtotal, amountDiscount, amountTax, amountTotal, currency
Related Information: planId, subscriptionId, productId, priceId
Provider-specific Fields: stripePaymentIntentId, stripeInvoiceId, stripeChargeId
Metadata: metadata (stores provider-specific metadata in JSONB format)

3. `subscriptions` - Subscriptions Table

Stores user subscription information:

User Association: userId, planId
Payment Provider: provider
Subscription Identifiers: subscriptionId, customerId
Subscription Status: status (active/trialing/past_due/canceled/incomplete/etc.)
Period Information: currentPeriodStart, currentPeriodEnd
Cancellation Information: cancelAtPeriodEnd, canceledAt, endedAt
Trial Information: trialStart, trialEnd
Metadata: metadata (JSONB format)

4. `usage` - Usage/Credits Table

Stores user credit balances and usage:

User Association: userId (unique)
Credit Balance: subscriptionCreditsBalance, oneTimeCreditsBalance
Balance Details: balanceJsonb (stores monthly/yearly allocation details in JSONB format)

5. `credit_logs` - Credit Logs Table

Records all credit changes:

User Association: userId
Change Amount: amount (positive for increase, negative for decrease)
Balance After Change: oneTimeBalanceAfter, subscriptionBalanceAfter
Change Type: type (one_time_purchase/subscription_grant/feature_usage/refund_revoke/etc.)
Related Order: relatedOrderId
Notes: notes

Core Modules

1. Actions Layer (`actions/`)

Server-side action functions that handle business logic:

actions/prices/: Pricing plan management (admin and public interfaces)
actions/stripe/: Stripe payment-related operations
actions/creem/: Creem payment-related operations
actions/orders/: Order queries (user and admin)
actions/usage/: Credit management and queries

2. API Routes (`app/api/`)

Handles HTTP requests and webhooks:

app/api/payment/: Payment-related APIs
- checkout-session: Creates checkout sessions
- verify-success: Verifies payment success
app/api/stripe/webhook/: Stripe webhook handling
app/api/creem/webhook/: Creem webhook handling

3. Library Files (`lib/`)

Reusable utility functions and clients:

lib/payments/: Payment-related utility functions
- provider-utils.ts: Payment provider utility functions
- credit-manager.ts: Credit management
- webhook-helpers.ts: Webhook helper functions
- types.ts: Type definitions
lib/stripe/: Stripe client
lib/creem/: Creem client

4. UI Components (`components/`)

Frontend display components:

components/home/Pricing.tsx: Pricing page (displays by category)
components/home/PricingAll.tsx: Pricing page (displays all plans)
components/home/PricingCardDisplay.tsx: Pricing card display component
components/home/PricingCTA.tsx: Pricing card CTA button

5. Admin Interface (`app/[locale]/(protected)/dashboard/`)

(admin)/prices/: Admin pricing plan management
(admin)/orders/: Admin order management
(user)/my-orders/: User order list
(user)/credit-history/: User credit history
(user)/subscription/: User subscription management

Payment Flow Overview

1. User Selects Plan

User selects a plan on the pricing page and clicks the purchase button.

2. Create Checkout Session

Frontend calls the /api/payment/checkout-session API, backend creates the appropriate checkout session based on the payment provider.

3. Redirect to Payment Page

User is redirected to the payment provider's payment page to complete the payment.

4. Payment Success Callback

After successful payment, user is redirected back to the application's /payment/success page, where the system verifies the payment status.

5. Webhook Processing

Payment provider sends webhook events (/api/stripe/webhook or /api/creem/webhook), system handles order creation, credit granting, and other operations.

6. Subscription Synchronization

For subscription payments, the system periodically synchronizes subscription status and handles renewal, cancellation, and other events.

Payment Type Descriptions

One-time Payment

Stripe: paymentType = 'one_time'
Creem: paymentType = 'onetime'
User makes a one-time purchase and receives one-time credits

Subscription Payment

Stripe: paymentType = 'recurring', recurringInterval = 'month'/'year'
Creem: paymentType = 'recurring', recurringInterval = 'every-month'/'every-year'
User subscribes monthly or yearly and receives credits periodically

Environment Variable Configuration

Stripe Configuration

STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_CUSTOMER_PORTAL_URL=/dashboard/subscription

Creem Configuration

CREEM_API_KEY=your_api_key
CREEM_WEBHOOK_SECRET=your_webhook_secret
CREEM_API_BASE_URL=https://api.creem.io/v1  # Optional, default value

Other Configuration

NEXT_PUBLIC_PRICING_PATH=/pricing
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
[email protected]