Invoice Sync & Save Card

This guide walks through the complete integration workflow between Flexprice and Stripe, from initial setup to automated invoice sync and payment processing. Integration Type: Bidirectional sync (Flexprice ↔ Stripe) Key Capabilities:

✅ Automatic invoice sync to Stripe
✅ Secure payment method storage
✅ Automated payment processing
✅ Real-time webhook reconciliation
✅ Customer and subscription sync

Step-by-Step Workflow

Phase 1: Initial Setup

Create Stripe Connection

Set up your Stripe connection with invoice sync enabled. This allows Flexprice to automatically sync invoices to Stripe and process payments.📚 Complete Guide: Stripe Connection Setup

Phase 2: Product Catalog Setup

Create Feature

Define a metered feature for usage-based billing:Endpoint: POST /api/v1/features

{
  "name": "API Calls",
  "key": "api_calls",
  "feature_type": "metered",
  "meter_id": "meter_api_requests",
  "description": "Number of API requests made"
}

Response:

{
  "id": "feat_1234567890abcdef",
  "name": "API Calls",
  "key": "api_calls",
  "feature_type": "metered",
      "status": "active"
    }

Create Plan

Create a subscription plan with pricing:Endpoint: POST /api/v1/plans

{
  "name": "Professional Plan",
  "key": "professional_plan",
  "billing_period": "monthly",
  "currency": "USD",
  "plan_type": "recurring",
  "prices": [
    {
      "feature_id": "feat_1234567890abcdef",
      "pricing_model": "tiered",
      "unit_price": "0.01",
      "tiers": [
        {
          "up_to": 1000,
          "unit_price": "0.01",
          "flat_fee": "10.00"
        },
        {
          "up_to": 10000,
          "unit_price": "0.008"
        },
        {
          "up_to": null,
          "unit_price": "0.005"
        }
      ]
    }
  ]
}

📚 Documentation:

🔗 API Reference:

Phase 3: Customer Onboarding

Create Customer

Create a customer in Flexprice (automatically synced to Stripe):Endpoint: POST /api/v1/customers

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "customer_id": "acme_corp_001",
  "metadata": {
    "company_size": "enterprise",
    "industry": "technology"
  }
}

Response:

{
  "id": "cus_1234567890abcdef",
  "name": "Acme Corporation",
  "email": "[email protected]",
  "status": "active"
}

Note: Customer is automatically created in Stripe when connection is configured.

Save Payment Method

Generate a secure link for customer to save their card:Endpoint: POST /api/v1/payments/customers/{customer_id}/setup/intentRequest:

{
  "success_url": "https://yourapp.com/payment/success",
  "cancel_url": "https://yourapp.com/payment/cancel",
  "provider": "stripe",
  "set_default": true
}

Response:

{
  "setup_intent_id": "seti_1234567890abcdef",
  "checkout_session_id": "cs_test_1234567890abcdef",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "status": "requires_payment_method",
  "usage": "off_session",
  "customer_id": "cus_1234567890abcdef",
  "created_at": 1765623942,
  "expires_at": 1765710343
}

Integration Steps:

Send checkout_url to customer via email or display in your application
Customer enters card details on Stripe’s hosted page
Card is saved and set as default payment method
Flexprice receives webhook confirmation from Stripe

📚 Documentation: Create a Customer 🔗 API Reference: Create Customer API Alternative: Save Card During Payment You can also save cards during invoice payment by using the payment creation endpoint with save_card_and_make_default flag: Endpoint: POST /api/v1/payments

{
  "destination_type": "invoice",
  "destination_id": "inv_1234567890abcdef",
  "payment_method_type": "payment_link",
  "payment_gateway": "stripe",
  "amount": "100.00",
  "currency": "USD",
  "save_card_and_make_default": true,
  "success_url": "https://yourapp.com/payment/success",
  "cancel_url": "https://yourapp.com/payment/cancel",
  "process_payment": true
}

📚 Documentation: Save Payment Method 🔗 API Reference: Create Payment API

Phase 4: Subscription Creation

Create Subscription

Create a subscription that will generate invoices automatically:Endpoint: POST /api/v1/subscriptions

{
  "customer_id": "cus_1234567890abcdef",
  "plan_id": "plan_1234567890abcdef",
  "start_date": "2024-01-20T00:00:00Z",
  "billing_anchor": "subscription_start",
  "collection_method": "charge_automatically",
  "metadata": {
    "contract_id": "CNT-2024-001"
  }
}

Response:

{
  "id": "sub_1234567890abcdef",
  "customer_id": "cus_1234567890abcdef",
  "plan_id": "plan_1234567890abcdef",
  "status": "active",
  "current_period_start": "2024-01-20T00:00:00Z",
  "current_period_end": "2024-02-20T00:00:00Z",
      "collection_method": "charge_automatically"
    }

📚 Documentation: Create a Subscription 🔗 API Reference: Create Subscription API

Phase 5: Usage Tracking

Track Usage Events

Send usage events throughout the billing period:Single Event: Endpoint: POST /api/v1/events

{
  "event_id": "evt_1234567890abcdef",
  "event_name": "api.request",
  "customer_id": "acme_corp_001",
  "timestamp": "2024-01-21T14:30:00Z",
  "properties": {
    "endpoint": "/api/v1/users",
        "method": "GET"
  },
  "idempotency_key": "unique_key_12345"
}

Bulk Events: Endpoint: POST /api/v1/events/bulk

{
  "events": [
    {
      "event_id": "evt_001",
      "event_name": "api.request",
      "customer_id": "acme_corp_001",
          "timestamp": "2024-01-21T14:30:00Z"
    }
  ]
}

Query Usage

Query aggregated usage data anytime:Endpoint: POST /api/v1/events/usage/meter

{
  "meter_id": "meter_api_requests",
  "customer_id": "acme_corp_001",
  "start_time": "2024-01-20T00:00:00Z",
      "end_time": "2024-02-20T00:00:00Z"
}

Response:

{
  "data": [
    {
      "customer_id": "acme_corp_001",
      "value": 15420,
      "start_time": "2024-01-20T00:00:00Z",
      "end_time": "2024-02-20T00:00:00Z"
    }
      ]
    }

📚 Documentation:

🔗 API Reference:

Bulk Ingest Events API

Phase 6: Invoice Generation & Sync

Invoice Auto-Generated

At end of billing period, Flexprice automatically:

Creates draft invoice with usage charges
Calculates pricing based on usage
Finalizes invoice
Syncs to Stripe (if connection configured)

Example Invoice:

{
  "id": "inv_01KCBAVXJC34H8JJGEJBD6F5MV",
  "customer_id": "cust_01KCB8BKDZ5D1VN0J1M7J404ZH",
  "subscription_id": "subs_01KCBAVKS24PJKT2GCDQ0GK8R6",
  "invoice_number": "INV-202512-00039",
  "invoice_status": "FINALIZED",
  "payment_status": "SUCCEEDED",
  "currency": "usd",
  "amount_due": "118.5",
  "total": "118.5",
  "amount_paid": "118.5",
  "line_items": [
    {
      "display_name": "WindowEdge Plan",
      "price_type": "FIXED",
      "amount": "10",
      "quantity": "1"
    },
    {
      "display_name": "Call Duration",
      "price_type": "USAGE",
      "amount": "108.5",
      "quantity": "1085"
    }
  ],
  "invoice_pdf_url": "https://pay.stripe.com/invoice/acct_1Rg0lDBVFqEMJNuG/test_YWNjdF8x.../pdf?s=ap",
  "metadata": {
    "stripe_hosted_invoice_url": "https://invoice.stripe.com/i/acct_1Rg0lDBVFqEMJNuG/test_YWNjdF8x...?s=ap"
  },
  "period_start": "2025-12-13T07:47:24.721Z",
  "period_end": "2025-12-13T07:47:38.139Z",
  "paid_at": "2025-12-13T07:48:15.771Z"
}

Sync Trigger Check

Flexprice checks if invoice should sync:

✅ Stripe connection exists
✅ Connection is active
✅ Invoice sync is enabled
✅ Customer synced to Stripe

→ Proceed with sync

Invoice Synced to Stripe

Invoice is automatically synced to Stripe:Response:

{
      "stripe_invoice_id": "in_1234567890abcdef",
      "status": "open",
      "payment_intent_id": "pi_1234567890abcdef",
      "hosted_invoice_url": "https://invoice.stripe.com/i/acct_.../test_...",
      "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf"
    }

📚 Documentation:

Phase 7: Payment Processing

Automatic Payment Attempt

When collection_method: "charge_automatically":

Stripe automatically attempts to charge customer’s default payment method
Payment intent is created and confirmed
Charge is processed immediately

If successful:

Stripe sends invoice.payment_paid webhook
Flexprice updates invoice status to “paid”
Customer receives payment confirmation email

Webhook Processing

Flexprice receives webhook at:

/api/v1/webhooks/stripe/{tenant_id}/{environment_id}

Webhook Flow:

Stripe sends webhook → Flexprice
Verify webhook signature
Extract invoice/payment ID from metadata
Update invoice status in Flexprice
Return 200 OK immediately

Payment Status Updated

Check invoice payment status:Endpoint: GET /api/v1/invoices/{invoice_id}

{
  "id": "inv_1234567890abcdef",
  "payment_status": "paid",
  "paid_at": "2024-02-20T00:05:00Z",
  "payment_details": {
    "payment_method": "card",
    "last4": "4242",
    "brand": "visa"
  }
}

📚 Documentation:

🔗 API Reference: Get Invoice API

Payment Collection Methods

Flexprice supports multiple payment collection methods for invoices. For detailed information on all payment options including offline payments, credit/wallet usage, and automated charging: 📚 Complete Guide: Record Payment & Collection Methods

Quick Overview

Charge Automatically (charge_automatically)

Best for: Subscriptions with saved payment methods
Stripe automatically charges customer’s default payment method
Immediate payment confirmation via webhooks

Send Invoice (send_invoice)

Best for: Manual payment workflows, B2B customers
Customer receives email with Stripe-hosted payment link
Flexible payment options

Key Integration Points

1. Entity Synchronization

Flexprice maintains bidirectional mapping between entities:

Flexprice Entity	Stripe Entity	Sync Direction
Customer	Customer	Bidirectional
Plan	Product	Outbound
Subscription	Subscription	Bidirectional
Invoice	Invoice	Outbound
Payment	Payment Intent	Inbound (via webhooks)

2. Invoice Sync Configuration

Invoice Sync:

{
  "invoice": {
    "inbound": false,
    "outbound": true
  }
}

Features:

Status synchronization: Payment status updates via webhooks
PDF generation: Access invoices as PDF from Stripe
Hosted pages: Use Stripe’s branded invoice pages

3. Payment Method Management

Setup Intent Flow:

Create Setup Intent via Flexprice API
Customer enters card on Stripe hosted page
Card saved and set as default
Webhook confirms setup completion

Payment Method Reuse:

Saved cards used for recurring charges
Off-session payments supported
Multiple payment methods per customer
Automatic default payment method selection

Error Handling

Common Scenarios

Scenario	Handling	Result
Customer already exists	Use existing Stripe customer	No error
Invoice already synced	Skip sync, return mapping	No error
Payment method missing	Return error, require setup	User must save card
Card declined	Stripe retries automatically	Eventual success or failure
Webhook signature fail	Log warning, skip processing	Security measure

Testing

Test Mode

Use Stripe test keys (sk_test_...) for development:

Test Cards: Use Stripe’s test card numbers
- Success: 4242 4242 4242 4242
- Decline: 4000 0000 0000 0002

Test Webhooks: Use Stripe CLI for local testing

stripe listen --forward-to localhost:8080/api/v1/webhooks/stripe/{tenant_id}/{environment_id}

Test Events: Trigger test webhooks from Stripe Dashboard

Production Checklist

Before going live:

Security Best Practices

API Key Management

Never expose API keys in client-side code
Use environment variables for key storage
Rotate keys regularly (quarterly recommended)
Use separate keys for test and production environments
Implement key scoping - use least privilege principle

Webhook Security

Verify webhook signatures - Flexprice does this automatically
Use HTTPS only for webhook endpoints
Implement replay protection via idempotency
Rate limit webhook endpoints
Log all webhook events for audit trails

Customer Data

Never store raw card numbers - use tokenized references only
PCI compliance - Stripe handles card data securely
Encrypt sensitive data at rest and in transit
Implement access controls for customer information
Regular security audits

Recommended Dashboards

Billing Overview: Total revenue, invoice count, payment success rate
Customer Health: Active subscriptions, churn rate, payment failures
Integration Health: Sync success rate, webhook delivery, API errors
Usage Analytics: Event volume by customer, feature adoption, usage trends

Support & Resources

API Documentation

Code Examples

Getting Help

Flexprice Support: [email protected]
Documentation: https://docs.flexprice.io
Community: https://community.flexprice.io
Stripe Support: https://support.stripe.com

Your Flexprice-Stripe integration is now complete and ready to handle automated usage-based billing with seamless payment processing! 🎉

Welcome

Stripe

Razorpay

Chargebee

QuickBooks

Invoice Sync & Save Card

Step-by-Step Workflow

Phase 1: Initial Setup

Phase 2: Product Catalog Setup

Phase 3: Customer Onboarding

Phase 4: Subscription Creation

Phase 5: Usage Tracking

Phase 6: Invoice Generation & Sync

Phase 7: Payment Processing

Payment Collection Methods

Quick Overview

Key Integration Points

1. Entity Synchronization

2. Invoice Sync Configuration

3. Payment Method Management

Error Handling

Common Scenarios

Testing

Test Mode

Production Checklist

Security Best Practices

API Key Management

Webhook Security

Customer Data

Recommended Dashboards

Support & Resources

API Documentation

Code Examples

Getting Help

Welcome

Stripe

Razorpay

Chargebee

QuickBooks

​Step-by-Step Workflow

​Phase 1: Initial Setup

​Phase 2: Product Catalog Setup

​Phase 3: Customer Onboarding

​Phase 4: Subscription Creation

​Phase 5: Usage Tracking

​Phase 6: Invoice Generation & Sync

​Phase 7: Payment Processing

​Payment Collection Methods

​Quick Overview

​Key Integration Points

​1. Entity Synchronization

​2. Invoice Sync Configuration

​3. Payment Method Management

​Error Handling

​Common Scenarios

​Testing

​Test Mode

​Production Checklist

​Security Best Practices

​API Key Management

​Webhook Security

​Customer Data

​Recommended Dashboards

​Support & Resources

​API Documentation

​Code Examples

​Getting Help

Step-by-Step Workflow

Phase 1: Initial Setup

Phase 2: Product Catalog Setup

Phase 3: Customer Onboarding

Phase 4: Subscription Creation

Phase 5: Usage Tracking

Phase 6: Invoice Generation & Sync

Phase 7: Payment Processing

Payment Collection Methods

Quick Overview

Key Integration Points

1. Entity Synchronization

2. Invoice Sync Configuration

3. Payment Method Management

Error Handling

Common Scenarios

Testing

Test Mode

Production Checklist

Security Best Practices

API Key Management

Webhook Security

Customer Data

Recommended Dashboards

Support & Resources

API Documentation

Code Examples

Getting Help