Stripe Connection Setup

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:

Prerequisites

Before setting up your Stripe connection, ensure you have:

Active Stripe Account - Sign up at stripe.com
API Keys - Available in your Stripe Dashboard
Webhook Endpoint - Configured in Stripe Dashboard
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
Publishable Key	Developers → API Keys	✅	Client-side Stripe calls, such as card collection
Webhook Secret	Developers → Webhooks → [Your Endpoint]	✅	Webhook signature verification

Finding Your Credentials

API Keys:
- Go to Stripe Dashboard → Developers → API Keys
- Copy your Secret key (starts with sk_) and your Publishable key (starts with pk_)
- Use test keys (sk_test_, pk_test_) for development
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
`setup_intent.succeeded`	Save the payment method a customer sets up, for later charges

Setting Up the Webhook

Go to Stripe Dashboard → Developers → Webhooks
Click + Add endpoint
Enter your webhook URL
Select the required events listed above
Click Add endpoint
Copy the Signing secret for your connection

Step 3: Create the Stripe Connection

Using Flexprice Dashboard

Open Stripe in Integrations

In the left sidebar, click Integrations, then click Connect on the Stripe card.

Enter your credentials

Enter a Connection name, your Secret key, and your Publishable key, then click Continue. Keys are encrypted and never shown again.

Connect Stripe sheet on the Credentials step with the connection name, secret key, and publishable key

Choose what syncs

Switch on what should move between Flexprice and Stripe: Pull plans, Pull subscriptions, Push invoices, and Push prices. Nothing syncs until you switch it on, and you can change it later. Click Continue.

Sync step with the Pull plans, Pull subscriptions, Push invoices, and Push prices switches

Add the webhook

The Webhook step shows your Webhook URL and the Events to send. Add them to a Stripe webhook as in Step 2, paste the signing secret Stripe gives you into Webhook signing secret, and click Connect Stripe.

Webhook step with the webhook URL, the events to send, and the webhook signing secret

To change the connection later, click Configure on the Stripe card. You can rename it and change what syncs. Keys can’t be shown or edited: to change them, disconnect and connect again.

Stripe connection settings with the name, sync switches, webhook, and Disconnect

API Request

Endpoint: POST /v1/connections Headers:

Content-Type: application/json
x-api-key: your_api_key
X-Tenant-ID: your_tenant_id
X-Environment-ID: your_environment_id

Request Body:

{
  "name": "Stripe Production",
  "provider_type": "stripe",
  "encrypted_secret_data": {
    "secret_key": "sk_live_...",
    "publishable_key": "pk_live_...",
    "webhook_secret": "whsec_..."
  }
}

Response

{
  "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

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

Webhook Security

HTTPS Only: Always use HTTPS for webhook endpoints
Signature Verification: Flexprice verifies all webhook signatures
Secret Management: Keep webhook secrets secure and rotate regularly
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

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

Next Steps

After setting up your Stripe connection:

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

​Overview

​Video Walkthrough

​Prerequisites

​Step 1: Gather Stripe Credentials

​Required Credentials

​Finding Your Credentials

​Step 2: Configure Webhook Endpoint in Stripe

​Webhook URL Format

​Required Webhook Events

​Setting Up the Webhook

​Step 3: Create the Stripe Connection

​Using Flexprice Dashboard

​API Request

​Response

​Security Best Practices

​Credential Management

​Webhook Security

​Troubleshooting

​Common Issues

​Debug Steps

​Next Steps