> ## Documentation Index
> Fetch the complete documentation index at: https://blueprint.codeandcreed.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Setup and Work with Stripe for Payments

<Warning>
  **DO NOT upgrade any Stripe dependencies** unless you're following their official migration guide and understand the breaking changes. Upgrading without proper migration can break your payment processing, webhooks, and billing functionality. The current Stripe version in the boilerplate is tested and stable.
</Warning>

<Warning>
  Setting up payment processing is only necessary when you have a working product that's ready to accept payments. During the initial learning and MVP development phase, you can keep payments disabled in your Titan config. Only set up a company and payment processing if you're ready to accept payments.
</Warning>

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

<Note>
  Assuming you have the ngrok url running, you can test the authentication flow locally.
</Note>

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

2. **Install Stripe CLI**

```bash theme={null}
brew install stripe/stripe-cli/stripe
```

3. **Login to Stripe**

```bash theme={null}
stripe login
```

4. **Listen for webhooks**

```bash theme={null}
stripe listen --forward-to <your-ngrok-url>/api/payments/webhook
```

5. **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:

```txt theme={null}
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_signing_secret"
```

6. **Run your app**

```bash theme={null}
bun run dev
```

7. **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 Destination'

   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):

   ```txt theme={null}
   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_PRODUCT_1_PRICE_ID="Your production price ID"
   ```

## Devising Your Pricing Strategy (In the Future)

### Plan Structure - The simpler the better

<Note>
  Remember, choose recurring subscriptions only when you can consistently deliver ongoing value.
  Forcing subscriptions when value is one-time will lead to high churn rates.
</Note>

1. **Free Tier**
   * Start with a simple free plan to attract users
   * Include basic but valuable features
   * Use as lead generation for premium plans

2. **Pro Plan**
   * Position as recommended option with visual cues
   * Price competitively (\$29-99/month range)
   * Target growing teams/businesses, for example
   * Include most-requested features

3. **Enterprise Plan (if applicable)**
   * Custom solutions and premium support
   * Use "Contact Sales" CTA
   * Focus on scalability features

### Add Negotiation Features

Integrate [SalesNip](https://salesnip.com/) if you want to offer AI-powered price negotiations.

## Prevent Disputes

[ByeDispute](https://byedispute.com) / [Chargeblast](https://www.chargeblast.com/) are tools that help you prevent disputes with your customers. They provide 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.

<Note>
  Monitor conversion rates and gather user feedback to optimize your pricing strategy.
  Keep pricing simple at launch to not confuse users. You can always adjust based on market response.
</Note>

## Common Issues & Troubleshooting

### Test cards aren't working locally

Make sure you're using the correct [Stripe test cards](https://stripe.com/docs/testing#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.

<Note>
  Never use production Stripe keys in development or test environments. Always use test mode keys for development.
</Note>