Skip to content

Billing: Paddle ​

Paddle is a merchant of record: it sells your plans in its own name and handles VAT, sales tax and invoices for you. Customers pay in Paddle’s secure checkout, which opens on your site, and Paddle’s notifications (webhooks) tell Replora which plan each account has paid for.

20 minutesSaaS operators (installation administrators)SaaS
Available inSingle userSaaS

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

Replora uses Paddle Billing (price ids pri_…), not Paddle Classic.

When payments are on ​

Paddle takes payments only when all of these are true:

  1. the installation runs the SaaS edition;
  2. the payment provider is Paddle (BILLING_PROVIDER=paddle, or Payments › Payment provider);
  3. the API key, the Client-side token and the Notification secret key are all set.

Without the secret nothing is switched on, on purpose: unsigned notifications could be forged to grant plans. Until then Plan & billing says payments are not set up 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
Paddle › Sandbox (test payments)PADDLE_SANDBOXOn: Paddle’s sandbox (sandbox-vendors.paddle.com) with test cards. Off (default): live payments
Paddle › API keyPADDLE_API_KEYThe server-side key that creates checkouts, portal sessions and changes subscriptions. Stored encrypted
Paddle › Client-side tokenPADDLE_CLIENT_SIDE_TOKENPublic token Paddle.js needs to open the checkout (test_… in the sandbox, live_… live)
Paddle › Notification secret keyPADDLE_WEBHOOK_SECRETThe secret of your notification destination; every notification’s signature is checked with it. Stored encrypted
—CASHIER_PATHFirst part of the notification address (default paddle → /paddle/webhook)

Values saved in the dashboard win over .env. Secret fields stay empty in the form; leave them empty to keep the stored value. After editing .env, run php artisan config:clear.

Sandbox and live don't mix

The sandbox and the live account have different keys, tokens, notification destinations and price ids. Switch all of them together, including the price ids of every plan.

Set up Paddle ​

1. Create products and prices ​

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

  1. In Paddle: Catalog › Products › New product, one per paid plan.
  2. Add a monthly recurring price, and a yearly one if the plan is sold yearly. Use the same amount and currency as the plan in Replora (the pricing page shows Replora’s numbers; Paddle charges its own, plus tax where it applies).
  3. Copy each price id (pri_…).
  4. In Administration › Plans, edit the plan and paste them into Paddle price id and Paddle yearly price id (see Plans & limits).

2. API key and client-side token ​

In Paddle: Developer tools › Authentication.

  1. Create an API key and copy it into API key.
  2. Create a client-side token and copy it into Client-side token.
ini
BILLING_PROVIDER=paddle
PADDLE_SANDBOX=true            # while testing
PADDLE_API_KEY=…
PADDLE_CLIENT_SIDE_TOKEN=test_…

3. Notification destination (webhook) ​

In Paddle: Developer tools › Notifications › New destination.

  • Type: URL. URL: https://your-site.com/paddle/webhook
  • Events:
EventUsed for
subscription.createdA new subscription: the account gets the plan of the paid price
subscription.updatedPlan changes, monthly ↔ yearly, cancellation scheduled or undone, payment past due
subscription.pausedA paused subscription stops giving access
subscription.canceledThe subscription ended: the account goes back to the default plan
transaction.completedA paid transaction (first charge or renewal), net of tax: used for affiliate commissions; also stores the transaction
transaction.updatedKeeps the stored transaction current
customer.updatedKeeps the stored customer details current

Save, then copy the destination’s secret key into Notification secret key (or PADDLE_WEBHOOK_SECRET). Payments switch on as soon as it is saved. Notifications without a valid Paddle-Signature are rejected; the address accepts up to 300 requests a minute.

Paddle opens checkouts only on approved domains. Replora opens them on its own page /pay/paddle.

  1. In Paddle: Checkout › Checkout settings, set the Default payment link to https://your-site.com/pay/paddle.
  2. Live accounts: request approval of your domain (Checkout › Website approval) and wait for it. The sandbox needs no approval.

5. Customer portal ​

Nothing to set up: Replora asks Paddle for a customer portal session each time a customer clicks Manage billing. There customers update their payment method, download invoices and see their subscription.

How it works for customers ​

your-site.com/plan
Plan & billing: managers buy and change plans here.Plan & billing: managers buy and change plans here.
Plan & billing: managers buy and change plans here.
What the customer doesWhat happens
Chooses a plan (Monthly or Yearly)Replora creates the Paddle customer and a transaction for the price (the plan id travels as custom data), then opens /pay/paddle, which loads Paddle.js and shows Paddle’s checkout overlay (“Opening Paddle’s secure checkout…”)
PaysBack on /plan?checkout=done. The plan changes only when Paddle’s notification confirms it
Opens an old payment linkA started checkout can be opened for 24 hours; after that: “This payment link has expired. Start again from Plan & billing.”
Picks another plan or interval while subscribedThe subscription is swapped to the new price and Paddle prorates
Cancel subscriptionCancelled at the end of the paid period; the plan stays until then
Resume subscriptionUndoes the cancellation while the paid period runs
Manage billingOpens Paddle’s customer portal (only after the account has paid once)
A payment failsThe subscription is past due; the plan keeps working for PLANS_GRACE_DAYS days (default 7) while Paddle retries

A paused subscription counts as ended: the account is on the default plan until it is resumed in Paddle. When Paddle doesn’t answer, the customer sees “The payment provider did not answer. Try again in a moment.” and the details go to the log (storage/logs).

Test with the sandbox ​

  1. Create a Paddle sandbox account and repeat steps 1–4 there (prices, API key, client-side token, notification destination, default payment link).
  2. Turn Sandbox (test payments) on.
  3. Buy a plan on Plan & billing with Paddle’s test card 4242 4242 4242 4242, any future date, CVC 100.
  4. Check Developer tools › Notifications in Paddle for delivered events, and Plan & billing for the new plan.

For live payments, turn the sandbox off and replace the API key, the token, the secret and every plan’s Paddle price ids with the live ones.

The checkout doesn't open

Usually the Default payment link isn’t set, or the domain isn’t approved yet (live). Check also that the Client-side token belongs to the same environment (sandbox or live) as the API key.

Switching to Stripe ​

Stripe and Paddle keep their own tables, so switching loses no data. Running Paddle subscriptions stay in Paddle and are no longer listened to: let them end, or cancel them, before switching. See Billing: Stripe.

Replora: see what your visitors see.