Skip to content

Billing: Stripe ​

With Stripe as the payment provider, customers buy a plan on Stripe Checkout, manage their card and invoices in Stripe’s customer portal, and Stripe’s webhooks tell Replora which plan each account has paid for. Replora never sees card numbers.

15 minutesSaaS operators (installation administrators)SaaS
Available inSingle userSaaS

Where: Settings › Installation, cards Payments and Stripe (/settings#installation), and the price ids in Administration › Plans. Everything can also be set in .env.

When payments are on ​

Stripe takes payments only when all of these are true:

  1. the installation runs the SaaS edition;
  2. the payment provider is Stripe (BILLING_PROVIDER=stripe, or Payments › Payment provider);
  3. the Publishable key, the Secret key and the Webhook signing secret are all set.

Without the signing secret nothing is switched on, on purpose: unsigned webhooks could be forged to grant plans. Until then the customers’ Plan & billing page says “Online payments are not set up on this site yet. Ask the site administrator to change your plan.” and administrators assign plans by hand.

The settings ​

Setting (Settings › Installation).env keyWhat it does
Payments › Payment providerBILLING_PROVIDERNone (plans are assigned by administrators), Stripe or Paddle. Takes effect for new requests right away
Stripe › Publishable keySTRIPE_KEYStarts with pk_ (pk_test_… in test mode)
Stripe › Secret keySTRIPE_SECRETStarts with sk_ (or a restricted rk_ key). Stored encrypted, never shown again
Stripe › Webhook signing secretSTRIPE_WEBHOOK_SECRETStarts with whsec_. The card shows the webhook address to use. Stored encrypted
—STRIPE_WEBHOOK_TOLERANCESeconds a webhook’s signature stays valid (default 300)
—CASHIER_PATHFirst part of the webhook address (default stripe → /stripe/webhook)

Values saved in the dashboard win over .env, which stays the fallback. Secret fields are kept empty in the form: leave them empty to keep the stored value. After editing .env, run php artisan config:clear (or php artisan optimize when you cache the config).

Set up Stripe ​

1. Create products and prices ​

There is no automatic sync: you create the prices in Stripe and copy their ids into Replora.

  1. In the Stripe dashboard open Product catalog › Add product, one product per paid plan (e.g. Starter).
  2. Add a recurring monthly price, and a recurring yearly price if the plan is sold yearly. Use the same amount and currency as the plan in Replora: the pricing page shows Replora’s numbers, Stripe charges its own.
  3. Copy each price’s id (price_…).
  4. In Administration › Plans, edit the plan and paste them into Stripe price id and Stripe yearly price id (see Plans & limits).

A plan without a Stripe price id for an interval is shown to customers as Not for sale online for that interval. Free plans need no price.

2. Enter the API keys ​

In Stripe: Developers › API keys. Copy the Publishable key and the Secret key into Settings › Installation › Stripe, or into .env:

ini
BILLING_PROVIDER=stripe
STRIPE_KEY=pk_live_…
STRIPE_SECRET=sk_live_…

3. Add the webhook ​

In Stripe: Developers › Webhooks › Add endpoint.

  • Endpoint URL: https://your-site.com/stripe/webhook
  • Events:
EventUsed for
customer.subscription.createdA new subscription: the account gets the plan of the paid price
customer.subscription.updatedPlan changes, monthly ↔ yearly, cancellation scheduled or undone, payment failed (past due)
customer.subscription.deletedThe subscription ended: the account goes back to the default plan
invoice.payment_succeededA paid invoice (first charge or renewal), net of tax: used for affiliate commissions
customer.updated, customer.deletedKeep the stored customer details current
payment_method.automatically_updatedKeep the stored card details current
invoice.payment_action_requiredPayments that need the customer to confirm (3-D Secure)

Instead of clicking, you can let Replora create the endpoint with exactly this list (while Stripe is the selected provider):

bash
php artisan cashier:webhook --url=https://your-site.com/stripe/webhook

Then open the endpoint in Stripe, reveal its Signing secret (whsec_…) and save it as Webhook signing secret (or STRIPE_WEBHOOK_SECRET=whsec_…). Payments switch on as soon as it is saved.

Use invoice.payment_succeeded, not invoice.paid

Replora listens to invoice.payment_succeeded. An endpoint that only sends invoice.paid still changes plans correctly, but affiliates earn no commission.

The webhook route accepts up to 300 requests a minute and rejects any request without a valid Stripe signature.

4. Turn on the customer portal ​

In Stripe: Settings › Billing › Customer portal, and save it once (in test mode and in live mode separately). This is the page Manage billing opens: customers update their card, download invoices and see their payment history. Without a saved portal configuration Stripe refuses the request and the customer sees “The payment provider refused: …”.

How it works for customers ​

your-site.com/plan
Plan & billing: the customer's plan and usage; managers see the buttons that buy and change plans.Plan & billing: the customer's plan and usage; managers see the buttons that buy and change plans.
Plan & billing: the customer's plan and usage; managers see the buttons that buy and change plans.
What the customer doesWhat happens
Chooses a plan (Monthly or Yearly) on Plan & billingReplora creates a Stripe customer for the account on first use and opens Stripe Checkout. The plan id travels as metadata
PaysStripe returns to /plan?checkout=done (“Thank you! Your plan changes as soon as the payment is confirmed…”). The plan changes only when the webhook confirms it, never because the browser came back
Cancels CheckoutBack on Plan & billing, nothing changed
Picks another plan or interval while subscribedThe running subscription is swapped to the new price; Stripe prorates the difference on the next invoice
Cancel subscriptionCancelled at the end of the paid period; the plan stays until then
Resume subscriptionUndoes the cancellation during the paid period
Manage billingOpens the Stripe customer portal (only after the account has paid once)
A payment failsThe subscription is past due (“Payment failed: update your card”); the plan keeps working for PLANS_GRACE_DAYS days (default 7) while Stripe retries

Only account managers see the buying buttons. Every account has one subscription; a second purchase replaces the plan rather than adding one. Payment actions are limited to 10 requests a minute per person. Stripe’s error messages are shown to the customer as “The payment provider refused: …”.

Test mode ​

  1. Use your Stripe test keys (pk_test_…, sk_test_…) and test-mode price ids. Test and live mode have different prices, webhooks and portal settings.

  2. To receive webhooks on a computer that Stripe can’t reach, use the Stripe CLI and put the secret it prints into Webhook signing secret:

    bash
    stripe listen --forward-to https://your-site.test/stripe/webhook
  3. Pay with test card 4242 4242 4242 4242, any future date and any CVC.

  4. Check the result on Plan & billing, and the delivered events under Developers › Webhooks in Stripe.

Before going live, replace the keys, the price ids in every plan and the signing secret with the live ones.

Nothing changes after paying?

The webhook didn’t arrive or was rejected. In Stripe, open the endpoint and look at the failed deliveries: a 400 means a wrong signing secret, a 404 means payments aren’t switched on (provider, keys or secret missing) or the address is wrong. Fix it and Resend the event.

Switching to Paddle ​

Stripe and Paddle keep their own tables, so switching BILLING_PROVIDER loses no data. Running Stripe subscriptions are not moved: they keep renewing in Stripe, but Replora stops listening to Stripe, so let them end (or cancel them) before you switch. See Billing: Paddle.

Replora: see what your visitors see.