DocsServer

Payments and invoicing

Payments online through Stripe, Mollie, Paddle or Lemon Squeezy, and invoicing with a catalogue, subscriptions, invoices and payments by transfer or in cash.

Two plugins work together. Payments takes money online, for anything an app sells. Invoicing bills people: a catalogue, charges, invoices, and payments online, by bank transfer or in cash. Each payment provider is a plugin of its own. To take payments with Stripe:

sluurp plugin add payments payments-stripe

Features include:

  • Stripe, Mollie, Paddle and Lemon Squeezy, each a plugin of its own: install only the ones you use
  • The provider’s own checkout page, so nothing about a card reaches your server
  • Payments settled by asking the provider, never on a call’s own word, and webhooks checked by their signatures
  • Refunds and chargebacks followed, and Stripe Connect for a marketplace’s sellers
  • Invoicing: issuers, a catalogue, subscriptions, invoices, bank transfers matched, a prepaid wallet and e-invoices

Payments and Invoicing are sold on their own, for $49 each, once per server: a swarm of servers counts as one. Invoicing comes with Payments. The provider plugins are free.

Payments

Set up a payee

A payee is who the money goes to: a name, a provider and its keys. Set payees up in the admin, under Payments, where each installed provider asks for what it needs. Keys are written there and never shown again.

ProviderPluginWhat a payee needs
Stripepayments-stripeA secret key (a restricted key with Checkout Sessions: Write is enough) and the webhook’s signing secret
Molliepayments-mollieAn API key
Paddlepayments-paddleAn API key, the webhook’s secret, and Paddle’s client-side token
Lemon Squeezypayments-lemonsqueezyAn API key, a store with one product, and the webhook’s signing secret

Point the provider’s webhook at /api/payments/webhook/<provider>/<payee>, as the admin shows it. Other plugins keep payees of their own, such as Invoicing’s issuers, and the admin lists those too.

Take a payment in the browser

app.ts
import "plugin:payments";

const { url } = await sluurp.payments.pay({
  payee: "shop", amount_cents: 1200, description: "Concert ticket", ref: `ticket:${ticket.id}`, back: location.href,
});
location.href = url;

// …and back here:
const paid = new URLSearchParams(location.search).get("paid");
if (paid) (await sluurp.payments.get(paid)).status; // "paid"
  • The payer goes to the provider’s page, and comes back to back with ?paid=<id>.
  • get(id) asks the provider how the payment went, and settles it if it was paid.
  • list({ ref: "ticket:*" }) gives the caller’s own payments, or everybody’s for a superuser. A trailing * matches the start of a ref.
  • Who may pay is a rule, set in the admin. By default, anybody signed in may.

Take a payment from a plugin

A plugin takes payments through the Payments plugin, with ctx.plugins.call. Once a payment is paid, the plugin’s queues/paid.ts is given it, and queues/refunded.ts if it is given back:

plugins/tickets/functions/api.ts
const { id, url } = ctx.plugins.call("payments", "start", { payee: "shop", cents: 1200, what: "Concert ticket", back, ref: ticket.id });

confirm asks the provider again, get reads the payment, and connect onboards a marketplace’s seller with Stripe Connect.

Paddle

Paddle is a merchant of record: it charges the sales tax and pays it where it is due. Its checkout opens on a page the server serves, /api/payments/page/<payee>, so a Paddle payee also needs Paddle’s client-side token, and the site approved in Paddle’s checkout settings. A pdl_sdbx_… key pays in Paddle’s sandbox.

Invoicing

Invoicing is the billing plugin. It suits anyone who bills people, from a sports club to a coworking space. To add it:

sluurp plugin add billing

The pieces

IssuerWho bills, for example a club or an association. Each has its own bank account, invoice numbering and payment provider
ItemA catalogue entry with a price and a unit: each, day, month or year
AccountWho a charge is for, for example a member. Payers come from the app’s own data (custodies by default), so billing doesn’t keep a separate list
ChargeOne item billed to one account: posted by hand (for a whole group, if needed) or made from a subscription
SubscriptionA recurring charge: lunch on Mondays and Thursdays, a monthly fee, a year of membership
InvoiceAn account’s open charges, with a number, a due date, and a structured reference used to match bank transfers
PaymentSettles invoices: by transfer, in cash, or online
WalletA prepaid balance. A booked meal is taken from it at once, and given back if cancelled in time

All amounts are whole cents, never floats.

Bill a period

app.ts
import "plugin:billing";

const billing = sluurp.billing;

await billing.charge({ accounts: [member.id], item: trip.id });                     // a charge, for one account or many
await billing.run({ issuer: club.id, from: "2026-09-01", to: "2026-09-30", dry: true }); // preview a run
await billing.run({ issuer: club.id, from: "2026-09-01", to: "2026-09-30" });            // bill subscriptions, invoice open charges

remind(id) emails a reminder for an unpaid invoice, and cancel(id) cancels it.

Collect payments

  • Online, through the issuer’s provider. billing.pay({ invoice, back }) returns a checkout url. The payer comes back to back with ?paid=<id>, and the provider’s webhook records the payment.
  • By bank transfer: pass bank statement lines to billing.match(lines), and each is matched to its invoice by reference. Use dry to preview.
  • In cash: billing.record(payment).
  • Wallet top-up: billing.pay({ account, issuer, amount_cents, back }), between €1 and €1,000.

E-invoices

With the peppol plugin (sluurp plugin add peppol), and where Peppol is how invoices travel, every invoice is also an e-invoice, for accounting software and the Peppol network: UBL 2.1 in the Peppol BIS Billing 3.0 profile (EN 16931).

Where Peppol applies is decided by the issuer’s country: its country if set, else its IBAN’s. That covers Belgium, the Netherlands, the Nordic countries, Ireland, Luxembourg, Austria, Estonia, Germany, France, Australia, New Zealand, Singapore, Japan and Malaysia. Elsewhere, no e-invoice is offered.

GET /api/billing/invoices/{id}/ubl

It carries the issuer’s name, address and company number (as its Peppol address), the payer, each line, the total, and how to pay: the bank account and the payment reference. Lines are VAT-exempt, as associations often bill; a negative total is a credit note. Whoever may see the invoice may download it.

Permissions

Managing billing (the catalogue, charges, runs and recording payments) is governed by the manage rule in billing’s settings; without one, only superusers can. Everyone else sees their own accounts and those they pay for.

billing.certificate(account, year) returns the tax-deductible amount paid per issuer for a year (in Belgium, for childcare for children under 14).

View as Markdown