Payments

Stack Auth provides a Payments app that integrates with Stripe to handle billing, subscriptions, and one-time purchases. The SDK provides methods for users and teams to create checkout URLs and manage items like credits, seats, or API quotas.

Overview

The Payments app enables you to:

• Accept Payments: Process subscriptions and one-time purchases through Stripe
• Manage Items: Track billable items like credits, seats, or features
• Create Checkout URLs: Generate Stripe checkout links directly from your SDK
• Track Products: List products owned by users or teams
• View Transactions: Monitor all payment activity in the dashboard

Enabling the Payments App

To use payments in your application:

1. Navigate to your Stack Auth dashboard
2. Go to the Apps section
3. Find and click on Payments in the app store
4. Click the Enable button
5. Follow the Stripe Connect onboarding flow to link your Stripe account

Stripe Integration

Connecting Your Stripe Account

Stack Auth uses Stripe Connect to securely integrate with your Stripe account:

1. In the Payments app settings, click Start Setup
2. Select your country of residence
3. You'll be redirected to Stripe's onboarding flow
4. Complete the required information:
   • Business details
   • Bank account information
   • Identity verification
5. Once approved, payments will be enabled for your project

You can also skip the Stripe onboarding and test payments in test mode first, where all purchases are free.

SDK Usage

The Payments functionality is available through the Customer interface, which is automatically available on CurrentUser and Team objects.

Creating Checkout URLs

Generate Stripe checkout URLs to let users purchase products:

For team purchases:

Managing Items

Items represent quantifiable resources like credits, API calls, or storage quotas. See the Item type reference for full details.

Getting Item Quantities

Retrieve the current quantity of an item for a user or team:

Real-time Item Updates (React Hook)

Use the useItem hook for real-time updates when quantities change:

Consuming Credits (Server-side)

Use tryDecreaseQuantity for race-condition-safe credit consumption:

Listing Products

List products owned by a user or team:

Granting Products (Server-side)

Grant products to users programmatically without requiring payment:

Dashboard Management

Products

Configure your products in the dashboard under Payments → Products:

• Create products with display names and pricing
• Configure items included with each product (e.g., 100 credits per purchase)
• Set up one-time or recurring billing
• Choose whether products are for users, teams, or custom customers

Customers

View and manage customer item balances under Payments → Customers:

• Select a customer type (User, Team, or Custom)
• View item quantities for each customer
• Manually adjust quantities with optional expiration dates
• Grant products directly to customers

Transactions

View all payment activity under Payments → Transactions:

• Filter by transaction type (Purchase, Subscription Renewal, etc.)
• Filter by customer type
• View transaction details including amount and products
• Refund eligible transactions (non-test, purchases with prices)

Customer Types

Stack Auth supports three types of payment customers:

• Users: Individual user accounts in your application
• Teams: Team or organization accounts
• Custom Customers: External entities identified by a custom ID (useful for integrations with external systems)

Test Mode

During development, you can use test mode:

1. Enable test mode in your Payments settings (or skip Stripe onboarding)
2. All purchases will be free and no money will be deducted
3. Test various scenarios before going live

Test Card Numbers

When in live mode with Stripe test credentials:

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Insufficient Funds: 4000 0000 0000 9995

See Stripe's testing documentation for more test scenarios.

Type References

For complete API documentation, see:

• Customer - Payment methods available on users and teams
• Item - Item and ServerItem type definitions
• ServerItem - Server-side item management methods

Best Practices

Security

1. Validate on Server: Always validate credit consumption on the server side
2. Use tryDecreaseQuantity: This method is atomic and prevents race conditions
3. Server-only Operations: Use grantProduct only on the server with proper authorization

Billing Management

1. Clear Item Names: Use descriptive display names for items
2. Set Expiration Dates: Use expiration dates for time-limited credits or features
3. Track Changes: Add descriptions when manually adjusting quantities

Customer Experience

1. Return URLs: Provide return URLs when creating checkout sessions
2. Real-time Updates: Use useItem() hooks to show live credit balances
3. Handle Insufficient Credits: Check balances before operations and show clear error messages

Pricing

Stack Auth does not charge additional fees for the Payments app. You'll only pay:

• Stripe's standard processing fees
• Any applicable Stripe Connect fees

Transaction limits are determined by your Stripe account tier.