> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Accept cards, Apple Pay, Google Pay, and 135+ currencies. Generate payment links automatically on every finalized invoice.

Stripe is the default payment gateway for global businesses on Fluxrate. When connected, Fluxrate creates a **Stripe Payment Link** every time an invoice is finalized. Your customers receive an email with a one-click payment link — no checkout integration needed on your end.

## Prerequisites

* A [Stripe account](https://dashboard.stripe.com/register) (live or test mode)
* A Stripe **Secret Key** (`sk_live_...` or `sk_test_...`)
* A Stripe **Webhook Signing Secret** (`whsec_...`)

## Setup

### Step 1 — Get your Stripe API Key

1. Go to [Stripe Dashboard → Developers → API Keys](https://dashboard.stripe.com/apikeys).
2. Copy your **Secret key** (`sk_live_...`).

<Warning>
  Never expose your secret key in client-side code. Fluxrate stores it encrypted — you only need to paste it once.
</Warning>

### Step 2 — Connect in Fluxrate

1. Open **Dashboard → Integrations**.
2. Click **Connect** next to Stripe.
3. Fill in the form:

| Field               | Value                                                              |
| ------------------- | ------------------------------------------------------------------ |
| **Connection Name** | A friendly label, e.g. `Production Stripe`                         |
| **Secret Key**      | Your Stripe secret key (`sk_live_...`)                             |
| **Webhook Secret**  | Leave blank for now — you'll add this after setting up the webhook |

4. Click **Create Connection**. Fluxrate generates a unique **Webhook URL** for your integration.

### Step 3 — Configure the Webhook in Stripe

1. Go to [Stripe Dashboard → Developers → Webhooks](https://dashboard.stripe.com/webhooks).
2. Click **Add endpoint**.
3. Paste the **Webhook URL** from Fluxrate (shown after connecting):
   ```text theme={null}
   https://api.fluxrate.co/api/v1/webhooks/stripe/tenant_{your_org_id}/{env_id}
   ```
4. Under **Events to send**, select:
   * `checkout.session.completed`
   * `payment_intent.succeeded`
   * `payment_intent.payment_failed`
   * `invoice.payment_succeeded`
   * `invoice.payment_failed`
5. Click **Add endpoint**.
6. Copy the **Signing secret** (`whsec_...`) shown on the webhook details page.

### Step 4 — Save the Webhook Secret

1. Back in Fluxrate, go to **Dashboard → Integrations → Manage** (Stripe).
2. Paste the signing secret into the **Webhook Secret** field.
3. Click **Save Changes**.

Your Stripe integration is now fully configured.

## How Payments Work

```mermaid theme={null}
sequenceDiagram
    participant Fluxrate
    participant Stripe
    participant Customer

    Fluxrate->>Stripe: Create Payment Link (invoice_id in metadata)
    Stripe-->>Fluxrate: payment_link.url
    Fluxrate->>Customer: Invoice email with payment link
    Customer->>Stripe: Pays via link
    Stripe->>Fluxrate: POST /webhooks/stripe/... (checkout.session.completed)
    Fluxrate->>Fluxrate: Verify Stripe-Signature header
    Fluxrate->>Fluxrate: Mark invoice as PAID
```

Fluxrate passes `invoice_id` and `customer_id` in the Stripe Payment Link metadata. When Stripe fires a webhook on payment completion, Fluxrate reads these values from `data.object.metadata` to identify the invoice and marks it as **PAID**.

## Webhook Payload Handling

Fluxrate reads the following fields from Stripe webhook payloads:

| Field                 | Source in payload                                | Purpose                               |
| --------------------- | ------------------------------------------------ | ------------------------------------- |
| `invoice_id`          | `data.object.metadata.invoice_id`                | Links event to a Fluxrate invoice     |
| `customer_id`         | `data.object.metadata.customer_id`               | Links event to a Fluxrate customer    |
| `amount`              | `data.object.amount` ÷ 100                       | Payment amount in major currency unit |
| `currency`            | `data.object.currency` (uppercased)              | ISO 4217 currency code                |
| `provider_payment_id` | `data.object.payment_intent` or `data.object.id` | Stripe payment reference              |

Events that trigger invoice payment:

* `checkout.session.completed`
* `payment_intent.succeeded`

## Managing the Integration

| Action                | How                                                     |
| --------------------- | ------------------------------------------------------- |
| Rotate API key        | Manage → enter new secret key → Save Changes            |
| Rotate webhook secret | Manage → enter new webhook secret → Save Changes        |
| Temporarily disable   | Toggle `is_active` via API or disconnect from dashboard |
| Remove entirely       | Dashboard → Integrations → ··· → Disconnect             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook signature verification failed">
    The `Stripe-Signature` header didn't match your stored webhook secret. Make sure you copied the **Signing secret** from Stripe (starts with `whsec_`), not the endpoint URL. Re-save the secret in Fluxrate and ensure Stripe is sending to the exact URL shown.
  </Accordion>

  <Accordion title="Invoice not marked as paid after payment">
    Check that your Payment Link was created with `invoice_id` in the metadata. Also confirm that the webhook event (`checkout.session.completed` or `payment_intent.succeeded`) is in your subscribed events list in Stripe Dashboard.
  </Accordion>

  <Accordion title="Webhook events not being received">
    Verify the webhook URL in Stripe Dashboard matches the one shown in Fluxrate exactly. Check **Dashboard → Integrations → Webhook Events** in Fluxrate to see all received events and their statuses.
  </Accordion>
</AccordionGroup>