Payments setup

Card payments run through Stripe Connect. Each business connects its own Stripe account, and the money goes straight to that business's bank account. This page covers both halves: the server settings a developer makes once, and the steps an administrator takes in Admin > Payments.

You need the payments.manage permission to change these settings.

Server setup

The server needs a Stripe account that acts as the Connect platform. Connect must be enabled on it. For a single business, that's normally your own Stripe account. A developer sets these in .env (see install):

Variable	Set it to
STRIPE_SECRET_KEY	The platform account's secret key
STRIPE_CONNECT_WEBHOOK_SECRET	The signing secret of the Connect webhook below
STRIPE_CONNECT_APPLICATION_FEE_PERCENT	A platform fee taken from each card payment. 0 takes none
STRIPE_CONNECT_COUNTRY	Country for new connected accounts. AU. A business's own default country is used first

Then in the Stripe dashboard, add a webhook endpoint that listens to events on connected accounts:

https://your-domain/api/v1/webhooks/stripe/connect

Send these events:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• checkout.session.expired
• payment_intent.succeeded
• charge.refunded
• account.updated
• account.application.deauthorized

Copy the endpoint's signing secret into STRIPE_CONNECT_WEBHOOK_SECRET. Without it, card payments can be taken but never marked as paid, and Admin > Payments warns: "The Stripe payment webhook is not set up on this server, so card payments will not be marked as paid."

If STRIPE_SECRET_KEY is missing, Admin > Payments says "Card payments are not set up on this server yet, so Stripe cannot be connected."

The webhook checks the Stripe-Signature header and rejects anything older than 300 seconds (STRIPE_WEBHOOK_TOLERANCE_SECONDS). Each Stripe event is recorded once, so a retry doesn't pay an invoice twice.

STRIPE_WEBHOOK_SECRET and the STRIPE_CHECKOUT_* and STRIPE_PORTAL_RETURN_URL variables belong to the product's own subscription billing, which is a separate Stripe feature at /api/v1/webhooks/billing/stripe. A one-off licence doesn't use it.

APP_URL must be the public address of the site, because pay links are built from it as APP_URL/pay/<token>.

Connect a business

1. Open Admin > Payments.
2. Under Card payments, choose "Connect Stripe". Stripe opens its own onboarding form for an Express account. Complete it with the business's details and bank account.
3. Stripe sends you back to Admin. Choose "Refresh status" to update.

If you leave onboarding half-way, the button reads "Continue setup". The panel shows the Stripe status, the account, whether the business can take payments and receive payouts, and any "Still needed" items Stripe is waiting on. If a platform fee is set, it shows "Platform fee N% of each card payment".

"Disconnect" removes the link. Existing invoices and payments stay. A business that disconnects in Stripe is disconnected here too, through the account.application.deauthorized event.

Card surcharge

"Card surcharge (%)" adds a percentage to card payments. It's shown to the customer as its own line on the pay page and on the invoice. Leave it at 0 to absorb card fees. It can go up to 5%. Keep it at or below what the card costs you, and check the current rules on surcharging with your accountant or Stripe.

Overdue reminders

Tick "Email customers about unpaid invoices" and choose which of the four steps to send:

Step	Default	Range
Before due date	3 days before	1 to 14 days before
On due date	On the day	Fixed
First overdue notice	7 days after	1 to 60 days after
Second overdue notice	14 days after	1 to 120 days after

Each reminder goes once per invoice and stops when the invoice is paid or credited. The scheduler checks hourly. A step is sent on its day or up to three days late if a run was missed. The wording is edited under Admin > Messages.

Statements

Tick "Email a monthly statement to customers who owe money" and choose the day of the month (1 to 28). Statements can also be sent from any customer's record at any time.

Test it

1. Use Stripe's test keys on a staging copy first.
2. Send yourself an invoice, open its pay link and pay with a Stripe test card.
3. Check the invoice shows the payment. If the payment receipt message is switched on, a receipt goes out as well.

Customers see the pay page at /pay/<token>. Staff see how it works in invoicing and payments.