​
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

​
Prerequisites

Before setting up your Stripe connection, ensure you have:
  1. Active Stripe Account - Sign up at 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

CredentialLocation in Stripe DashboardRequiredPurpose
Secret KeyDevelopers → API Keys✅Server-side API calls
Webhook SecretDevelopers → 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 TypePurpose
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:

​
API Request

Endpoint: POST /api/v1/connections Headers: 
Content-Type: application/json
Authorization: Bearer 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_...",
    "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

  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

IssueCauseSolution
Connection test failsInvalid API keysVerify keys in Stripe Dashboard
Webhook not receivedIncorrect webhook URLCheck URL format and endpoint
Signature verification failsWrong webhook secretUpdate webhook secret in connection
Customer sync failsMissing account permissionsCheck 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
For detailed API documentation, see the API Reference.