Chargebee Connection Setup

​

Overview

• Creating item families, items, and item prices in Chargebee
• Synchronizing customers to Chargebee
• Syncing invoices to Chargebee for payment collection
• Receiving webhook notifications from Chargebee

​

Prerequisites

1. Active Chargebee Account - Sign up at chargebee.com
2. API Key - Available in your Chargebee Dashboard
3. Webhook Endpoint - Configured in Chargebee Dashboard
4. Flexprice Environment - Valid tenant and environment IDs

​

Step 1: Gather Chargebee Credentials

​

Required Credentials

​

Finding Your Credentials

1. Site Name:
   • Go to Chargebee Dashboard → Settings → API & Webhooks
   • Your site name is displayed at the top (e.g., acme-test)
2. API Key:
   • Go to Chargebee Dashboard → Settings → API & Webhooks → API Keys
   • Copy your API key (starts with your site name)
   • Use test API keys for development
3. Webhook Credentials:
   • Choose any username and password: Chargebee signs webhooks with HTTP Basic auth
   • Enter the same pair on the Chargebee webhook and in Flexprice

​

Step 2: Configure Webhook Endpoint in Chargebee

​

Webhook URL Format

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

​

Required Webhook Events

​

Setting Up the Webhook

1. Go to Chargebee Dashboard → Settings → API & Webhooks → Webhooks
2. Click + Add New Webhook
3. Enter your webhook URL
4. Select the required events listed above
5. Configure Basic Authentication with your webhook username and password
6. Click Save

​

Step 3: Create Chargebee Connection

​

Using Flexprice Dashboard

1

Open Chargebee in Integrations

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

2

Enter your credentials

Enter a Connection name, your Site (the part before .chargebee.com in your Chargebee address), and your API key, then click Continue. Keys are encrypted and never shown again.

3

Choose what syncs

Switch on Push invoices to send Flexprice invoices to Chargebee when they are finalised. Nothing syncs until you switch it on, and you can change it later. Click Continue.

4

Add the webhook

The Webhook step shows your Webhook URL and the payment_succeeded event. Enter a Webhook username and Webhook password, use the same pair for Basic Authentication on the Chargebee webhook (Step 2), and click Connect Chargebee.

​

API Request

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

{
  "name": "Chargebee Production",
  "provider_type": "chargebee",
  "encrypted_secret_data": {
    "site": "acme-production",
    "api_key": "acme-production_api_key_...",
    "webhook_username": "webhook_user",
    "webhook_password": "webhook_password"
  }
}

​

Response

{
  "id": "conn_1234567890abcdef",
  "name": "Chargebee Production",
  "provider_type": "chargebee",
  "status": "active",
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}

​

Editing an Existing Connection

• Connection name: Update the friendly name for the connection
• Push invoices: Enable or disable invoice sync
• Webhook username and Webhook password: Enter new values to replace them, or leave them blank to keep the current ones

​

Security Best Practices

​

Credential Management

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

​

Webhook Security

1. HTTPS Only: Always use HTTPS for webhook endpoints
2. Basic Authentication: Use Basic Auth for webhook verification (recommended)
3. Secret Management: Keep webhook credentials secure and rotate regularly
4. Rate Limiting: Implement rate limiting on webhook endpoints

​

Troubleshooting

​

Common Issues

​

Debug Steps

1. Check Chargebee Dashboard: Verify API key and site name
2. Test API Key: Use Chargebee API to test key validity
3. Monitor Webhooks: Check webhook delivery logs in Chargebee
4. Review Logs: Check Flexprice application logs for errors

​

Next Steps

1. Create Item Family: Create an item family in Chargebee (required for plan sync)
2. Sync Plans: Sync your Flexprice plans to Chargebee
3. Test Invoice Sync: Create a test invoice and sync to Chargebee
4. Monitor Webhooks: Ensure webhook events are being received
5. Go Live: Switch to production credentials when ready