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

# Stripe

> Connect a Stripe account: API key, webhook events, checkout redirect and Price ID mapping.

Keyplar reads your Stripe account, receives its webhooks, and maps purchases to your catalog by
**Price ID**.

## Connect Stripe

<Steps>
  <Step title="Create a restricted or secret API key">
    In the Stripe Dashboard, go to **Developers → API keys** and copy a secret key (`sk_live_…`,
    or `sk_test_…` while you're testing).

    Keyplar uses it to read checkout sessions, invoices, subscriptions and customers — for
    post-checkout fulfillment and for [import](/import).
  </Step>

  <Step title="Add the webhook endpoint">
    Go to **Developers → Webhooks → Add endpoint** and use your store's webhook URL:

    ```
    https://yourstore.keyplar.com/webhooks
    ```

    Subscribe to exactly these events:

    | Event                           | Why                                                 |
    | ------------------------------- | --------------------------------------------------- |
    | `checkout.session.completed`    | One-off purchases                                   |
    | `invoice.paid`                  | Subscription payments, first and every renewal      |
    | `charge.refunded`               | Refunds — revokes the order's benefits              |
    | `customer.subscription.created` | Starts tracking a subscription                      |
    | `customer.subscription.updated` | Plan changes, pauses, status changes                |
    | `customer.subscription.deleted` | Cancellation — revokes that subscription's benefits |

    Other events are accepted and ignored, so a broader subscription does no harm — it's just
    noise.
  </Step>

  <Step title="Copy the signing secret">
    On the endpoint you just created, reveal the **Signing secret** (`whsec_…`).
  </Step>

  <Step title="Save both in Keyplar">
    In your admin panel, open **Settings** → the **Stripe** panel:

    * **Secret key** — the `sk_…` key
    * **Webhook secret** — the `whsec_…` signing secret
    * **Account ID** — optional (`acct_…`), only if you want the connection pinned to one
      account

    Save. The panel switches to **Configured**.
  </Step>

  <Step title="Set the post-checkout redirect">
    The Stripe panel shows the URL to use:

    ```
    https://yourstore.keyplar.com/orders/complete?session_id={CHECKOUT_SESSION_ID}
    ```

    <Warning>
      Keep `{CHECKOUT_SESSION_ID}` written exactly like that, braces included. Stripe substitutes
      the real session ID at redirect time — if you replace it yourself, fulfillment breaks.
    </Warning>

    Where to put it depends on how you sell:

    * **Payment Links** — the link's **After payment** setting, "Redirect customers to a page"
      ([Stripe docs](https://docs.stripe.com/payment-links/post-payment#change-confirmation-behavior))
    * **Checkout Sessions** — the `success_url` parameter when you create the session
  </Step>
</Steps>

## Map products by Price ID

In Stripe, a **Product** is what you sell and a **Price** is how it's charged. Keyplar maps on
the **Price ID** (`price_…`), so monthly and annual versions of the same thing can grant
different benefits — or the same ones.

<Steps>
  <Step title="Copy the Price ID">
    In Stripe, open the product and copy the ID of the specific price, not the product. It
    starts with `price_`, not `prod_`.
  </Step>

  <Step title="Paste it into the Keyplar product">
    **Products** → your product → the **Stripe** mapping field.
  </Step>
</Steps>

<Tip>
  Selling the same thing monthly and annually? Create one Keyplar product with the benefits, and
  map only one Price to it — then either add the second Price to a second Keyplar product, or
  keep a single product and accept that both prices grant the same benefits.
</Tip>

## Things specific to Stripe

### Keyplar issues and owns the license keys

Stripe has no license concept, so keys for Stripe orders are generated by Keyplar. That means
you **can regenerate** a key from **Licenses** if a customer leaks theirs — something that isn't
possible for gateways that manage keys themselves.

### Subscription renewals arrive as invoices

Every renewal is `invoice.paid`, and lands as its own order linked to the subscription. Renewal
orders are hidden from the main order lists so your history stays readable — open the
subscription to see them all.

### Import brings orders, not entitlements

[Importing](/import) from Stripe backfills customers, orders and subscriptions, and creates
placeholder catalog products for anything unmapped. There are no entitlements in Stripe to
import — benefits come from your Keyplar catalog once the mapping is in place.

## Testing

Use a `sk_test_…` key and Stripe's test mode, with a separate webhook endpoint pointed at the
same URL. Stripe's test card `4242 4242 4242 4242` with any future expiry works for a full
round-trip through checkout, redirect and order creation.

<Note>
  Test-mode and live-mode credentials can't be held at the same time — the Stripe panel holds
  one secret key. Swap to live keys when you're ready, and update the webhook secret to match
  the live endpoint.
</Note>