This guide covers working with payments with Stripe in Titan.

Titan comes with a complete Stripe integration that handles payments, subscriptions, and webhooks. All the necessary code is already implemented to process payments and update your database when payment events occur.

​
Testing payments locally

Assuming you have the ngrok url running, you can test the authentication flow locally.

  1. Set config.payments.enabled to true in config.ts

  2. Install Stripe CLI

brew install stripe/stripe-cli/stripe
  1. Login to Stripe
stripe login
  1. Listen for webhooks
stripe listen --forward-to <your-ngrok-url>/api/payments/webhook
  1. Copy the webhook secret

When you run the Stripe CLI webhook listener, it will print a webhook signing secret. Copy this value and add it to your .env file:

STRIPE_WEBHOOK_SECRET="whsec_your_webhook_signing_secret"
  1. Run your app
bun run dev
  1. Test the payment flow

Navigate to your pricing page and attempt to make a payment using the Stripe test card details:

  • Card number: 4242 4242 4242 4242
  • Expiry date: Any future date
  • CVC: Any 3 digits
  • Postal code: Any 5 digits

When the payment is successful, you should see the event logged in your Stripe CLI and the subscription created in both Stripe and your database.

​
Configuring payments in production

  1. Switch to Production Stripe mode

    a. Login to your Stripe Dashboard

    b. In the top-right corner, toggle from ‘Test Mode’ to ‘Live Mode’

    c. Create a new product in production or replicate your test products

    d. Copy your Production Price ID(s) for your subscriptions/products

    e. Copy your Production API Keys:

    • NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
    • STRIPE_SECRET_KEY

  2. Set up the Production Webhook

    a. In your Stripe Dashboard, go to ‘Developers’ > ‘Webhooks’

    b. Click ‘Add Endpoint’

    c. Set the endpoint URL to https://[your-production-domain]/api/payments/webhook

    d. Select the following events:

    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • checkout.session.completed
    • invoice.payment_succeeded
    • invoice.payment_failed

    e. Copy the webhook signing secret for your environment variables

  3. Update Environment Variables

    Ensure these environment variables are set in your production environment (e.g., Vercel):

    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="Your production publishable key"
STRIPE_SECRET_KEY="Your production secret key"
STRIPE_WEBHOOK_SECRET="Your production webhook signing secret"
NEXT_PUBLIC_STRIPE_PRICE_ID="Your production price ID"

​
Prevent Disputes

ByeDispute is a tool that helps you prevent disputes with your customers. It provides a dashboard to monitor your disputes and a set of tools to help you resolve them.

Pricing is simple and transparent. Worth paying for if you’re starting to get disputes. Just setup a few rules and it’ll handle the rest.

​
Common Issues & Troubleshooting

​
Test cards aren’t working locally

Make sure you’re using the correct Stripe test cards for your testing.

​
Webhooks aren’t being received

  • Verify your ngrok URL is correct and the tunnel is active
  • Ensure the webhook endpoint in Stripe matches exactly your application’s endpoint path
  • Check your STRIPE_WEBHOOK_SECRET is correctly set in your .env file

​
Payment succeeded but subscription not created

Check the logs in your Stripe CLI output and your application server logs for any error messages.

Never use production Stripe keys in development or test environments. Always use test mode keys for development.