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

# Stripe

> Stripe integration for checkout and payments

Nozle uses Stripe for payment processing and embedded checkout. Each Nozle organization connects its own Stripe account, so your customers pay into your Stripe account, not Nozle's.

## Setup

Connect Stripe from the Nozle dashboard or API using your Stripe secret key. Nozle stores it server-side and uses it only to create customers, payment sessions, and webhook endpoints for your organization.

You do not expose the Stripe secret key in your frontend. Browser checkout uses:

* your Nozle publishable key (`pk_nozle_...`) to call Nozle
* your Stripe publishable key (`pk_test_...` / `pk_live_...`) to mount Stripe Embedded Checkout

## What Nozle handles

| Feature           | How it works                                                               |
| ----------------- | -------------------------------------------------------------------------- |
| **Checkout**      | Embedded Stripe checkout for a Nozle invoice                               |
| **Subscriptions** | Managed in Nozle; paid plans activate only after payment succeeds          |
| **Invoices**      | Generated by Nozle, payment collected via Stripe                           |
| **Webhooks**      | Nozle registers and validates Stripe webhooks per connected Stripe account |

## Webhook setup

When a Stripe provider is connected, Nozle automatically registers a Stripe webhook endpoint using that Stripe account's secret key. Stripe sends payment events back to Nozle at:

```text theme={null}
{NOZLE_PUBLIC_API_URL}/webhooks/stripe/{organization_id}?code={stripe_provider_code}
```

Nozle stores the webhook signing secret returned by Stripe and validates the `Stripe-Signature` header on every webhook request.

Required events for checkout:

* `payment_intent.succeeded`
* `payment_intent.payment_failed`
* `payment_intent.canceled`

Your Nozle public API URL must be reachable by Stripe. If the webhook is missing or blocked, Stripe can collect payment but Nozle will not reliably mark invoices paid or activate payment-gated subscriptions.

## Checkout flow

1. Customer selects a plan in your app (via React SDK or API)
2. Nozle computes the exact invoice/proration while preserving the current paid plan
3. Nozle creates a Stripe embedded Checkout Session when an external payment remains due
4. Customer enters payment details in the embedded checkout
5. Stripe sends a payment intent webhook to Nozle
6. Nozle marks the invoice paid and applies the subscription change

If prepaid credits fully cover the invoice, Nozle returns a completed checkout response and Stripe is not called.

For credit top-ups, add-ons, and other one-off purchases, create the invoice first and then call checkout with `invoice_id`. Those flows do not use subscription activation rules.