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

# Stripe Connection Setup

> Complete guide to setting up and configuring Stripe connections in Flexprice

## Overview

A Stripe connection in Flexprice stores encrypted credentials that allow the system to interact with your Stripe account for:

* Creating customers in Stripe
* Processing payment links via Stripe Checkout
* Receiving webhook notifications from Stripe
* Synchronizing customer data between systems

## Video Walkthrough

Watch this step-by-step guide to setting up your Stripe connection:

<div className="relative pb-[62.5%] h-0">
  <iframe src="https://www.loom.com/embed/2763c3c7dccd41d48c1e6b4f7182c4b3?sid=9a69681f-ff64-4a02-9a65-8ee3d76a544b&autoplay=0" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen className="absolute top-0 left-0 w-full h-full" />
</div>

## Prerequisites

Before setting up your Stripe connection, ensure you have:

1. **Active Stripe Account** - Sign up at [stripe.com](https://stripe.com)
2. **API Keys** - Available in your Stripe Dashboard
3. **Webhook Endpoint** - Configured in Stripe Dashboard
4. **Flexprice Environment** - Valid tenant and environment IDs

## Step 1: Gather Stripe Credentials

### Required Credentials

| Credential         | Location in Stripe Dashboard             | Required | Purpose                        |
| ------------------ | ---------------------------------------- | -------- | ------------------------------ |
| **Secret Key**     | Developers → API Keys                    | ✅        | Server-side API calls          |
| **Webhook Secret** | Developers → Webhooks → \[Your Endpoint] | ✅        | Webhook signature verification |

### Finding Your Credentials

1. **API Keys:**
   * Go to Stripe Dashboard → Developers → API Keys
   * Copy your `Secret key` (starts with `sk_`)
   * Use test keys (`sk_test_`) for development

2. **Webhook Secret:**
   * Go to Stripe Dashboard → Developers → Webhooks
   * Create or select your webhook endpoint
   * Click "Reveal signing secret"
   * Copy the secret (starts with `whsec_`)

## Step 2: Configure Webhook Endpoint in Stripe

### Webhook URL Format

```
https://api.cloud.flexprice.io/v1/webhooks/stripe/tenant_01K1TJDVNSN7TWY8CZY870QMNV/env_01K1TJJF0CJR410C6QVPYQTNV0
```

### Required Webhook Events

Configure these events in your Stripe webhook endpoint:

| Event Type           | Purpose                                                               |
| -------------------- | --------------------------------------------------------------------- |
| `checkout.session *` | Track payment link completions from Stripe Checkout                   |
| `customer *`         | Synchronize customer data changes between Stripe and Flexprice        |
| `payment_intent *`   | Monitor payment processing status and handle payment lifecycle events |

### Setting Up the Webhook

1. Go to Stripe Dashboard → Developers → Webhooks
2. Click **+ Add endpoint**
3. Enter your webhook URL
4. Select the required events listed above
5. Click **Add endpoint**
6. Copy the **Signing secret** for your connection

## Step 3: Create Stripe Connection via API

### Using Flexprice Dashboard

You can create a Stripe connection directly from the Flexprice dashboard:

<Frame>
  <Frame>
    <img src="https://mintcdn.com/flexprice/_FTvPy7G6Ow7yaiY/connection.png?fit=max&auto=format&n=_FTvPy7G6Ow7yaiY&q=85&s=64aa36da10af1b047f2ea22380c501e1" alt="Stripe Connection Setup" width="2886" height="1726" data-path="connection.png" />
  </Frame>
</Frame>

### API Request

**Endpoint:** `POST /api/v1/connections`

**Headers:**

```http theme={null}
Content-Type: application/json
Authorization: Bearer your_api_key
X-Tenant-ID: your_tenant_id
X-Environment-ID: your_environment_id
```

**Request Body:**

```json theme={null}
{
  "name": "Stripe Production",
  "provider_type": "stripe",
  "encrypted_secret_data": {
    "secret_key": "sk_live_...",
    "webhook_secret": "whsec_...",
  }
}
```

### Response

```json theme={null}
{
  "id": "conn_1234567890abcdef",
  "name": "Stripe Production",
  "provider_type": "stripe",
  "status": "active",
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}
```

## Security Best Practices

### Credential Management

1. **Environment Separation**: Use different keys for test/production
2. **Key Rotation**: Regularly rotate your Stripe API keys
3. **Access Control**: Limit API key permissions in Stripe
4. **Encryption**: All credentials are encrypted at rest in Flexprice

### Webhook Security

1. **HTTPS Only**: Always use HTTPS for webhook endpoints
2. **Signature Verification**: Flexprice verifies all webhook signatures
3. **Secret Management**: Keep webhook secrets secure and rotate regularly
4. **Rate Limiting**: Implement rate limiting on webhook endpoints

## Troubleshooting

### Common Issues

| Issue                        | Cause                       | Solution                            |
| ---------------------------- | --------------------------- | ----------------------------------- |
| Connection test fails        | Invalid API keys            | Verify keys in Stripe Dashboard     |
| Webhook not received         | Incorrect webhook URL       | Check URL format and endpoint       |
| Signature verification fails | Wrong webhook secret        | Update webhook secret in connection |
| Customer sync fails          | Missing account permissions | Check Stripe account permissions    |

### Debug Steps

1. **Check Stripe Dashboard**: Verify API keys and webhook configuration
2. **Test API Keys**: Use Stripe CLI to test API key validity
3. **Monitor Webhooks**: Check webhook delivery logs in Stripe
4. **Review Logs**: Check Flexprice application logs for errors

## Next Steps

After setting up your Stripe connection:

1. **Test Customer Sync**: Create a test customer and sync to Stripe
2. **Create Payment Links**: Test payment link creation and flow
3. **Monitor Webhooks**: Ensure webhook events are being received
4. **Go Live**: Switch to production keys when ready