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

# Stripe Plugin

> Stripe checkout & subscriptions for Streamly — keys, webhooks, Connect fees, billing flow, and troubleshooting.

**Stripe** (`payments.stripe`) is a Streamly **plugin** in the **payment** category.

Stripe is the primary card/checkout rail for viewer plan purchases and renewals. Webhooks keep Streamly subscriptions in sync after payment succeeds, fails, or cancels.

## Learn the service

Watch this overview of the vendor platform (helpful before you paste keys into Streamly).

<Frame caption="Working with Stripe Elements and Checkout Sessions — Stripe Developers.">
  <iframe src="https://www.youtube.com/embed/aW6AcSR1Oyg" title="Working with Stripe Elements and Checkout Sessions" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />
</Frame>

## At a glance

| | |
| - | - |
| **Plugin ID** | `payments.stripe` |
| **Category** | payment · runtime `builtin` |
| **Version** | 1.0.0 |
| **Status** | Wired |
| **Admin** | `/admin/plugins` |
| **Webhook** | `POST /api/webhooks/stripe` |

## Capabilities

* `payments.checkout`
* `payments.subscriptions`
* `payments.webhooks`
* `payments.connect`

## When to use it

* Global card checkout for subscription OTT plans
* Automatic renewals via Stripe Subscriptions
* Optional Connect + application fee for platform takes

## How it works

### Checkout flow

| Step | Actor | What happens |
| - | - | - |
| **1** | Viewer | Chooses a plan on the storefront |
| **2** | Streamly | Creates a Stripe Checkout / subscription session |
| **3** | Viewer | Pays in Stripe |
| **4** | Stripe → Streamly | Signed webhook hits `/api/webhooks/stripe` |
| **5** | Streamly | Activates or renews access |

1. Operator pastes API keys + webhook signing secret.
2. Viewer starts checkout from a plan.
3. Stripe confirms payment and POSTs to Streamly.
4. Streamly activates or renews the subscription.

<Note>
  Webhook endpoint: `POST /api/webhooks/stripe`
</Note>

## Activation keys

Configure in `/admin/plugins` → **Stripe** → Configure. Secret fields stay server-side — never commit them or expose as `NEXT_PUBLIC_*` unless the key is intentionally public (e.g. Stripe publishable key).

| Key | Label | Required | Secret | Description | Vendor docs |
| - | - | - | - | - | - |
| `publishableKey` | Publishable key | Yes | No | `pk_test_…` / `pk_live_…` for Checkout.js / Elements | [API keys](https://docs.stripe.com/keys) |
| `secretKey` | Secret key | Yes | Yes | Server-only `sk_…` | [API keys](https://docs.stripe.com/keys) |
| `webhookSecret` | Webhook signing secret | Yes | Yes | `whsec_…` for `/api/webhooks/stripe` | [Signatures](https://docs.stripe.com/webhooks/signatures) |
| `connectWebhookSecret` | Connect webhook signing secret | Optional | Yes | When using Stripe Connect | [Connect webhooks](https://docs.stripe.com/connect/webhooks) |
| `applicationFeePercent` | Viewer application fee percent | Optional | No | Platform fee % on Connect direct charges | [Collect fees](https://docs.stripe.com/connect/direct-charges#collect-fees) |

### Optional env fallbacks

`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_CONNECT_WEBHOOK_SECRET`, `STRIPE_VIEWER_APPLICATION_FEE_PERCENT` — prefer the plugin UI for Envato / multi-tenant installs.

## Setup guide

<Steps>
  <Step title="Get API keys">
    Open [Stripe API keys](https://dashboard.stripe.com/apikeys). Start in **test mode**.
  </Step>

  <Step title="Install Stripe in Streamly">
    `/admin/plugins` → install **Stripe** → paste publishable + secret keys.
  </Step>

  <Step title="Create webhook endpoint">
    Developers → Webhooks → Add endpoint:

    `https://YOUR_HOST/api/webhooks/stripe`

    Copy the signing secret into `webhookSecret`. Include checkout / subscription / invoice events your deploy expects.
  </Step>

  <Step title="Create plans">
    Define sellable plans in `/admin/plans`.
  </Step>

  <Step title="End-to-end test">
    Buy with a [test card](https://docs.stripe.com/testing). Confirm `/admin/subscriptions` updates after the webhook.
  </Step>

  <Step title="Go live">
    Swap to live keys, create a live webhook endpoint, re-test one real small charge if needed.
  </Step>
</Steps>

## Admin & Settings paths

| Path | Purpose |
| - | - |
| `/admin/plugins` | Install & activation keys |
| `/admin/plans` | Products viewers can buy |
| `/admin/subscriptions` | Active / pending entitlements |
| `/dashboard/settings` | Tenant payment entrypoint (when exposed) |

## Official vendor documentation

* [Stripe API keys](https://docs.stripe.com/keys)
* [Webhook signatures](https://docs.stripe.com/webhooks/signatures)
* [Connect webhooks](https://docs.stripe.com/connect/webhooks)
* [Application fees](https://docs.stripe.com/connect/direct-charges#collect-fees)
* [Testing](https://docs.stripe.com/testing)

## What Streamly stores vs Stripe

| In Stripe | In Streamly |
| - | - |
| Customer, PaymentMethod, Subscription objects | Local subscription / entitlement rows synced from webhooks |
| Invoices & tax (if configured in Stripe) | Plan catalog, access gates, admin UI |

Never log full PANs — Streamly uses Stripe-hosted Checkout / Elements patterns.

## FAQ

<AccordionGroup>
  <Accordion title="Checkout works but access never unlocks">
    Almost always a webhook problem: wrong URL, missing events, or bad `webhookSecret`. Check Stripe → Developers → Webhooks → recent deliveries.
  </Accordion>

  <Accordion title="Should I put the secret key in NEXT_PUBLIC_?">
    No. Only `publishableKey` is public. `secretKey` and webhook secrets are server-only.
  </Accordion>

  <Accordion title="Kids / restricted profiles">
    Billing can be blocked by product rules for kids profiles — check viewer profile type before debugging Stripe.
  </Accordion>
</AccordionGroup>

## Related

* [Payments / Billing](/configuration/stripe)
* [Subscriptions](/admin-dashboard/subscriptions)
* [Plans](/admin-dashboard/plans)
* [PayPal Plugin](/plugins/paypal)
* [Bank Transfer](/plugins/bank-transfer)
* [Plugins Overview](/plugins/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.