Stripe Customer Synchronization

Overview

Customer synchronization ensures that customers exist in both Flexprice and Stripe with linked identifiers, enabling:

On-demand sync: Customers are synced to Stripe only when needed for payments
Payment link creation for any Flexprice customer
Card payment processing with automatic customer sync
Automatic customer creation from Stripe webhooks
Consistent customer data across platforms
Efficient payment processing workflows

Synchronization Flow

Customer sync now works on-demand with bidirectional support:

Key Concepts

On-Demand Sync: Customers are synced to Stripe only when payment interactions occur
Entity Integration Mapping: Links Flexprice customers to Stripe customer IDs
Metadata Storage: Customer metadata stores cross-platform references
Payment-Triggered Sync: Sync happens automatically during payment flows
Duplicate Prevention: Intelligent checks prevent duplicate customer creation
Performance Optimization: No unnecessary syncs for customers who never make payments

Customer Data Model

Flexprice Customer Structure

{
  "id": "cust_1234567890abcdef",
  "external_id": "customer_external_123",
  "name": "John Doe",
  "email": "john@example.com",
  "address_line1": "123 Main St",
  "address_line2": "Apt 4B",
  "address_city": "New York",
  "address_state": "NY",
  "address_postal_code": "10001",
  "address_country": "US",
  "metadata": {
    "stripe_customer_id": "cus_stripe123abc"
  },
  "environment_id": "prod",
  "tenant_id": "tenant_123",
  "status": "active",
  "created_at": "2024-01-20T10:30:00Z"
}

Stripe Customer Structure

{
  "id": "cus_stripe123abc",
  "name": "John Doe",
  "email": "john@example.com",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "metadata": {
    "flexprice_customer_id": "cust_1234567890abcdef",
    "flexprice_environment": "prod",
    "external_id": "customer_external_123"
  },
  "created": 1642680600
}

Synchronization Methods

1. On-Demand Sync (Payment-Triggered)

Primary Method: Customers are automatically synced to Stripe when payment interactions occur.

Payment Link Creation

When creating a payment link, the system automatically ensures the customer exists in Stripe: Endpoint: POST /api/v1/payments Request:

{
    "amount": 20,
    "currency": "usd",
    "destination_id": "inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC",
    "destination_type": "INVOICE",
    "payment_method_type": "PAYMENT_LINK",
    "process_payment": true,
    "payment_gateway": "stripe",
    "success_url": "https://admin.flexprice.io/customer-management/invoices/inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC?page=1",
    "cancel_url": "https://admin.flexprice.io/customer-management/invoices/inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC?page=1"

}

Internal Flow:

Check if customer has stripe_customer_id in metadata
Check entity integration mapping table
If not synced → Create customer in Stripe automatically
Create payment link with synced customer

Card Payment Processing

When processing card payments, the system ensures customer sync: Endpoint: POST /api/v1/payments Request:

{
    "amount": 20,
    "currency": "usd",
    "destination_id": "inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC",
    "destination_type": "INVOICE",
    "payment_method_type": "CARD",
    "process_payment": true,
    "payment_gateway": "stripe",
    "success_url": "https://admin.flexprice.io/customer-management/invoices/inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC?page=1",
    "cancel_url": "https://admin.flexprice.io/customer-management/invoices/inv_01K3K2N0FY0Z7Z6RHR6EMGJ8AC?page=1"

}

Internal Flow:

Validate payment amount against invoice remaining balance
Ensure customer is synced to Stripe (auto-sync if needed)
Process payment with Stripe customer using saved payment method

2. Manual Sync (Optional)

For advanced use cases, manual sync is still available: Endpoint: POST /api/v1/integrations/sync/customer Request:

{
  "customer_id": "cust_1234567890abcdef",
  "provider": "stripe",
  "sync_direction": "flexprice_to_provider"
}

3. Automatic Sync (Stripe → Flexprice)

Customers created in Stripe are automatically synced via webhooks. Webhook Event: customer.created Webhook Payload:

{
  "id": "evt_1234567890abcdef",
  "type": "customer.created",
  "data": {
    "object": {
      "id": "cus_stripe123abc",
      "name": "John Doe",
      "email": "john@example.com",
      "address": {
        "line1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "metadata": {
        "flexprice_environment": "prod"
      }
    }
  }
}

Sync Configuration

Required Fields for Sync

Field	Flexprice → Stripe	Stripe → Flexprice	Notes
`name`	✅	✅	Customer full name
`email`	✅	✅	Primary email address
`address_line1`	✅	✅	Street address
`address_city`	✅	✅	City
`address_state`	✅	✅	State/province
`address_postal_code`	✅	✅	ZIP/postal code
`address_country`	✅	✅	Country code

Optional Fields

Field	Description
`address_line2`	Apartment/suite number
`phone`	Phone number
`external_id`	Your internal customer ID
`metadata`	Custom key-value pairs

Sync Process Details

On-Demand Sync Flow (Payment-Triggered)

Stripe → Flexprice Sync Flow (Unchanged)

Customer Linking

Metadata Storage

Customer linking is maintained through metadata fields: In Flexprice Customer:

{
  "metadata": {
    "stripe_customer_id": "cus_stripe123abc",
    "stripe_sync_timestamp": "2024-01-20T10:30:00Z"
  }
}

In Stripe Customer:

{
  "metadata": {
    "flexprice_customer_id": "cust_1234567890abcdef",
    "flexprice_environment": "prod",
    "flexprice_sync_timestamp": "2024-01-20T10:30:00Z"
  }
}

Link Verification

You can verify customer links using the API: Endpoint: GET /api/v1/customers/{customer_id}/integrations Response:

{
  "customer_id": "cust_1234567890abcdef",
  "integrations": [
    {
      "provider": "stripe",
      "external_id": "cus_stripe123abc",
      "sync_status": "linked",
      "last_sync": "2024-01-20T10:30:00Z"
    }
  ]
}

Duplicate Prevention

Email-Based Deduplication

The system prevents duplicate customers using email addresses:

Check Existing: Look for customers with same email
Merge Strategy: Update existing customer with new data
Link Creation: Create cross-platform links
Audit Trail: Log all sync operations

External ID Matching

For customers with external IDs:

Priority Matching: External ID takes precedence over email
Fallback to Email: If no external ID match, use email
Manual Resolution: Conflicts require manual intervention

Error Handling

Common Sync Errors

Error	Cause	Resolution
”Customer not found”	Invalid customer ID	Verify customer exists
”Email already exists”	Duplicate email in Stripe	Check for existing customer
”Invalid email format”	Malformed email address	Fix email format
”Stripe API error”	Stripe connection issue	Check Stripe credentials

Sync Failure Recovery

When sync fails:

Log Error: Record failure with details
Retry Logic: Automatic retry with exponential backoff
Manual Intervention: Admin can retry failed syncs
Notification: Alert on persistent failures

Testing Customer Sync

Test Environment Setup

Test Stripe Account: Use Stripe test mode
Test Customers: Create test customers in Flexprice only
Webhook Testing: Use ngrok for local webhook testing

On-Demand Sync Testing Flow

Create Test Customer: Add customer in Flexprice (no sync yet)
Verify No Sync: Customer should NOT exist in Stripe initially
Create Payment Link: Trigger payment link creation
Verify Auto-Sync: Customer should now exist in Stripe
Test Card Payment: Process card payment with same customer
Verify Reuse: Should use existing Stripe customer (no duplicate)

​Overview

​Synchronization Flow

​Key Concepts

​Customer Data Model

​Flexprice Customer Structure

​Stripe Customer Structure

​Synchronization Methods

​1. On-Demand Sync (Payment-Triggered)

​Payment Link Creation

​Card Payment Processing

​2. Manual Sync (Optional)

​3. Automatic Sync (Stripe → Flexprice)

​Sync Configuration

​Required Fields for Sync

​Optional Fields

​Sync Process Details

​On-Demand Sync Flow (Payment-Triggered)

​Stripe → Flexprice Sync Flow (Unchanged)

​Customer Linking

​Metadata Storage

​Link Verification

​Duplicate Prevention

​Email-Based Deduplication

​External ID Matching

​Error Handling

​Common Sync Errors

​Sync Failure Recovery

​Testing Customer Sync

​Test Environment Setup

​On-Demand Sync Testing Flow