Stripe Configuration
Set up the Stripe payment gateway, its API keys and its webhook.
Overview
Stripe is one of the payment gateways bundled with Light Store. It powers both the redirect checkout and the in-page checkout overlay.
Everything is configured in the admin dashboard under Configuration > Gateways (/admin/gateways), in the Stripe section.
| Field | Required | Description |
|---|---|---|
| Enable Stripe | Yes | Shows Stripe as a payment option at checkout |
| Publishable Key | Yes | Public key (pk_live_...), used by the in-page checkout overlay |
| Secret Key | Yes | Server-side key (sk_live_...), used to create and read checkout sessions |
| Webhook Secret | No | Signing secret (whsec_...) of the webhook endpoint you create in Stripe |
| Sandbox Mode | No | Uses Stripe test keys and skips SSL certificate verification |
Live mode requires your store to be served over HTTPS. Use Sandbox Mode with test keys while you are still on plain HTTP.
API keys
- Go to the Stripe Dashboard and pick the mode you intend to use with the Test mode switch. Test keys pair with Sandbox Mode in the store, live keys pair with it switched off.
- Open Developers > API keys.
- Copy the Publishable key into the Publishable Key field in the store.
- Reveal and copy the Secret key into the Secret Key field.
- Enable Enable Stripe and save.
At this point checkout already works: a customer who completes payment and returns to the store has their order settled on return.
Webhook
The webhook is what settles orders when the customer closes the tab before returning, and it is the only way delayed payment methods (SEPA debit, Bacs, boleto, Konbini, and similar) can ever settle.
-
Open the Webhooks tab in the Stripe Dashboard, in the same mode as your keys.
-
Click Add endpoint.
-
Set the endpoint URL to your store's webhook URL:
https://your-store.com/payments/webhook/stripeThe exact URL is also printed under the Webhook Secret field in the store.
-
When asked which events to listen to, select only these three:
checkout.session.completedcheckout.session.async_payment_succeededcheckout.session.async_payment_failed
-
Save the endpoint, click Reveal on its Signing secret and copy the
whsec_...value into the Webhook Secret field in the store, then save.
Until the Webhook Secret is filled in, the endpoint answers every Stripe delivery with a 503 and no order is
fulfilled through webhooks. Stripe will show the endpoint as failing.
Why only these three events?
The store ignores every other event type. Subscribing to payment_intent.*, charge.* or "all events" only fills
your Stripe event log with deliveries that are acknowledged and dropped.
Testing
With Sandbox Mode on and test keys in place, use Stripe's test card 4242 4242 4242 4242 with any future expiry date and any CVC.