Payments and invoicing: overview
Beta
Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.
Payments and invoicing is being rolled out: as long as the feature is not enabled on your tenant, BillingAccount and BillingWebhook manifests are rejected.
What it is for
Payments and invoicing lets you collect payments from your own customers, white-labelled: your application sends a cart, the platform returns a link to a payment page in your colours, then issues the invoice. The money goes directly to your Stripe or PayPal accounts: the platform never holds it.
Three ways to get paid:
| Mode | For | Page |
|---|---|---|
one_time | a one-off purchase: one cart, one payment, one invoice | Collect a payment |
subscription | a subscription: the platform charges every period and invoices it | Subscriptions |
usage | pay-as-you-go: you send the month's cart, the platform charges the saved payment method | Pay-as-you-go |
How it works, on your side
- You configure your payment account once, with a
BillingAccountmanifest: display name, your Stripe and/or PayPal keys, your legal invoicing details, your logo and colours. See Configure your payment account. - Your application calls the payment API with an application token of your organisation: create a cart, charge a customer, refund, read invoices.
- Your customers pay on the payment page, without creating an account: they reach it through a signed, time-limited link.
- The platform notifies you of every event (payment succeeded, subscription past due,
invoice issued, refund…) through signed webhooks that you declare with
BillingWebhook. - You write to your customers: the platform sends no e-mail to your customers. Your application sends confirmations, invoices and reminders, based on the webhooks.
What you get
- A payment page in your colours, under
https://pay.dev.stackngo.fr/<slug>/…, offering Stripe (card) and/or PayPal depending on your configuration. - An invoice for every successful payment and a credit note for every refund, in Factur-X format (PDF/A-3 with embedded structured data), numbered without gaps, in your name and with your legal mentions. See Invoices.
- A customer portal through a signed link, where your customer finds their invoices, subscriptions and payment method.
- A payments report that answers "who does this money belong to?", by application and by tag. See Who the money belongs to.
The API in short
| Address | https://billing-api.dev.stackngo.fr |
| Authentication | Authorization: Bearer <token>: an application token of your organisation (see Configure your payment account) |
| Amounts | decimal strings ("49.00"), ISO 4217 currency (EUR); each line is rounded to the cent |
| VAT | computed per category and rate, following the European standard EN 16931 |
| Errors | application/problem+json (RFC 9457): title, status, detail, and per-field errors[] |
| Safe retries | Idempotency-Key header: optional when creating a cart, required for a charge and a refund |
| Lists | limit (1 to 100, default 25) and cursor; the response returns next_cursor |
Your token can only do what you allowed the application to do in your BillingAccount
(carts, charges, subscriptions, refunds, invoices:read).
What you can expect
- One payment account per tenant, which can use Stripe, PayPal or both.
- No catalogue to maintain: each cart carries its own lines, prices and VAT.
- Your keys stay yours: you manage them like your other secrets; the platform uses them to collect payments on your behalf, and never displays them.
- Transaction fees are those of your Stripe or PayPal contract.
- Invoices are kept for 10 years, even if you remove your payment account.
Not available yet
- Custom domains for the payment page: it is served under
pay.dev.stackngo.fr. - SEPA direct debit: only card (Stripe) and PayPal are offered.
- Several currencies in one invoice: an invoice, a cart and a subscription each have a single currency.
- Transmission of invoices to e-invoicing platforms (PDP): you download your Factur-X invoices and send them yourself.