billing help · For merchants
Workspace manual
Everything a workspace owner, admin or finance viewer does: products and plans, gateways, transactions, refunds and disputes, discount codes, payment links, payees and payouts, analytics, the API.
- How a workspace works
- Setup checklist
- Products and plans
- Gateways (credential sets)
- Connecting your provider account
- Payees and revenue share
- Payouts, the ledger and statements
- Payments and their statuses
- Customers and access
- Subscriptions
- Refund requests
- Disputes and evidence
- Discount codes
- Payment links
- Analytics and insights
- Exports and the audit log
- Members, roles and signing in
- Two-step sign-in and security settings
- Branding and policies
- Notifications
- API keys and outbound webhooks
- Licensing (software products)
How a workspace works
A workspace is your store on the platform. It has its own members, products, gateways, customers and payments, and nobody outside it can see them. The platform takes no fee from your payments: money goes straight from the buyer to your own provider account.
The building blocks#
| Term | What it is |
|---|---|
| Member | A person who signs in to the workspace: Owner, Admin or Finance viewer (Members and roles). |
| Credential set | Your API keys for one provider account (Stripe, PayPal, Square or Authorize.net) in one environment, test or live (Gateways). |
| Product | Something you sell. It has a pay page at /pay/<workspace>/<product>, a refund policy and a list of providers (Products and plans). |
| Plan | A price of a product: free, one-time, monthly, quarterly or annual, with an optional free trial. A product can have several plans. |
| Customer | A buyer, identified by email address within your workspace. Customers can have an account to see receipts and manage subscriptions. |
| Payment (transaction) | One charge, with a status and, once paid, a confirmation code ENC-XXXX-XXXX-CC (Payments and statuses). |
| Subscription | A recurring plan of one customer, renewed by the provider (Subscriptions). |
Text description
1. The buyer chooses a plan and a provider on the pay page. 2. The server creates a checkout and sends the buyer to the provider's hosted page. 3. The buyer pays there; card or bank details never reach this server. 4. The provider sends the buyer back to the return page, which only shows "confirming". 5. The provider's signed webhook confirms the payment; only then the payment becomes Paid and gets its confirmation code. 6. The receipt email with the code goes out and the customer account shows the payment.
How money and status move#
- Buyers pay on the provider's hosted page. Card and bank details never reach this server.
- A payment is Paid only when the provider's signed webhook confirms it. The return page the buyer sees is only a hint. That is why every credential set needs its webhook registered.
- Refunds, disputes, renewals and cancellations arrive the same way and update the payment or subscription by themselves.
The Overview screen#
- Revenue, last 30 days — gross revenue of paid payments, as a figure and a sparkline. Admins limited to some products see only those products.
- Getting started — the setup steps that are still open: add a gateway, verify it, create a product, take a test payment. It disappears when everything is done.
- Insights — the main findings of the financial analysis; Analytics and insights explains them.
Open Help (the ? at the top right of every screen) for the page that explains the screen you are on.
Setup checklist
Do these in order. Each step links to its page.
Before you take any payment#
- Accept the invitation from the platform and choose a strong password. Members and roles
- Branding and policies — accent colour, logo, support email, the receipt footer, and your terms, privacy and refund policy texts. Branding and policies
- A test credential set for at least one provider. Paste its webhook value, Verify, and Put in service (Test). Gateways
- A product with a plan, bound to the test credential set, and status Active. Products and plans
- A test payment on the pay page with the provider's test card. Check that it shows Paid with a confirmation code, and that the receipt email arrived. Your first payment in 15 minutes
- A test refund from the payment's page. Check that it reaches Refunded.
Going live#
- Create a live credential set for the same provider: live keys, live webhook, Verify, Put in service (Live).
- On each product, under Pay with, switch the provider to the live set.
- Make one small real payment and refund it.
- Invite your team with the least role each person needs. Members and roles
- Choose your notifications: payments above an amount, disputes, refund reviews, the daily summary. Notifications
Products and plans
Products lists everything you sell. New product creates one; open a product to edit it.
Details#
| Field | Meaning |
|---|---|
| Name, Address | The name buyers see and the last part of the pay page address: /pay/<workspace>/<address>. Lower-case letters, digits and dashes. |
| Description | Shown on the pay page. Blank lines start new paragraphs. |
| Price type | Fixed (the plan's price) or Custom amount, where the buyer chooses an amount between your minimum and maximum. |
| Options | Allow a quantity. |
| Payment methods | Card, and US bank account (ACH through Stripe, eCheck through Authorize.net). |
| Status | Draft (hidden), Active (on sale), Archived (no new sales; history kept). |
| Refunds | Refund window in days, full or partial refunds or none, and self-refunds per customer per year. Used when customers ask for a refund. Refund requests |
| Search title, Search description | What search engines and link previews show. Empty uses the name and description. |
Plans#
A product needs at least one plan. Add plan takes a name, a billing interval and a price:
- Free — no payment; customers press Start free in their account.
- One-time — charged once.
- Monthly, quarterly, annual — renewed by the provider until canceled. Trial days add a free trial; the first charge comes when the trial ends.
Plans cannot be edited after creation, because payments refer to them. To change a price, add a new plan and archive the old one. Existing subscriptions keep their plan; customers can move with Change plan.
Pay with#
For each provider, choose which credential set takes this product's payments, or Not offered. A set appears to buyers only once it is in service (Test or Live). Tiles also hide when a provider cannot take a plan: Square, for example, cannot start free trials.
The pay page#
Open pay page shows the page as buyers see it. The page carries the product's search title, description and a generated preview image, so links shared on social networks show the product and its price.
Licensing#
Software products sold with license keys have a Licensing panel on the product page. See Licensing.
Gateways (credential sets)
A credential set holds the keys of one provider account in one environment (test/sandbox or live/production). Settings → Gateways lists them. Owners add and change sets; admins can see them.
Where the platform offers it, you can also connect a Stripe, PayPal or Square account without copying keys: see Connecting your provider account. The rest of this page is about sets with your own keys.
Text description
A credential set starts as Draft. Verify makes one authenticated call to the provider; when it succeeds the set is Verified. Put in service needs the webhook value too and makes the set Test or Live, depending on its environment. A set can be disabled by hand, or automatically after three provider authentication failures in a row (the owners are emailed), and enabled again.
Adding a set#
- Add credential set → choose the provider, the environment and a label (for example "Stripe live").
- Paste the keys. Each field says where to find the value at the provider. Secret values are stored sealed and shown afterwards as their last four characters only.
- On the set's page, copy the Webhook endpoint URL and register it at the provider with the events listed under Events to send.
- Paste the provider's webhook value (Stripe: signing secret; PayPal: webhook ID; Square: signature key; Authorize.net: signature key).
- Verify credentials makes one authenticated call to the provider.
- Put in service (Test) or (Live). The set can now be chosen on products.
The step-by-step guides for each provider start from creating the provider account: Stripe, PayPal, Square, Authorize.net.
Rules worth knowing#
- Changing any value returns the set to Draft until it is verified again. Products using it stop offering it meanwhile.
- Three provider authentication failures in a row disable the set and email the owners. Fix the keys, then Re-enable as Draft, verify and put it back in service.
- The environment is checked against the keys: a live key in a test set is refused.
- Managed by the platform sets were added by the platform operator. You can use them on products but not change them.
Testing the webhook#
The set's page shows Last check and the signature check. After a test payment, the payment page shows the provider's events under History. If a payment stays Pending after the buyer paid, the webhook is not arriving: see Troubleshooting payments.
Connecting your provider account
Where your platform offers it, Settings → Gateways shows Connect an account. Instead of copying API keys and registering a webhook, you sign in at the provider and allow the platform to take payments for your account.
- The money goes to your own provider account. The platform charges no fee.
- You enter your sign-in at the provider only; this site never sees it.
- Only owners can connect, continue or end a connection.
If the panel is missing, your platform has not set the connection up, or it manages gateways for your workspace. You can still add a set with your own keys: see Gateways.
Connect#
- Press Connect Stripe, Connect PayPal or Connect Square (Test first, if offered).
- A short page says where you are going, then the provider's pages open. Complete them.
- The provider sends you back to the new credential set.
The set goes into service on its own when the provider accepts payments on the account. Then choose it for that provider on your products (Products and plans).
Statuses#
Text description
A connected set starts as Onboarding while the workspace fills in the provider's own pages. When the provider knows the account but does not accept payments on it yet, the set is Restricted. When the provider accepts payments the set is Enabled and goes into service as Test or Live. An enabled account can become restricted again, which takes the set out of service and e-mails the owners. From any of the three the connection can end as Revoked: the workspace disconnects, or the provider reports that access was withdrawn. Revoked is final.
| Connection | What to do |
|---|---|
| Onboarding | The provider's pages were not completed. Continue at the provider. |
| Restricted | The provider needs something more — a document, a confirmed e-mail address, a location. The set's page says what. |
| Enabled | Nothing. The set is in service. |
| Revoked | The connection has ended. Connect again to get a new set. |
If an account that was Enabled becomes Restricted, the set leaves service, your products stop offering that provider, and the owners get an e-mail. It returns on its own when the provider is satisfied.
Check status now asks the provider at once. Otherwise the status follows the provider's own reports and an hourly check.
Provider notes#
- Stripe — bank payments (ACH) are offered through a connected set only when Stripe has activated them for your account; until then products show cards for that set.
- PayPal — you need a PayPal Business account with a confirmed e-mail address.
- Square — your account needs an active US-dollar location with card processing. With several locations, choose on the set's page where payments are taken.
- Authorize.net — has no connection of this kind. Open an Authorize.net account leads to its sign-up page; afterwards add the account's keys with Add credential set (Authorize.net guide).
Pause or end a connection#
- Disable for now takes the set out of service and keeps the connection. Re-enable brings it back.
- Disconnect is final for the set. Refunds and disputes of earlier payments can then no longer be handled from here, so settle them first. Your provider account is not closed.
One provider account can be connected to one workspace at a time.
Payees and revenue share
A payee is anyone who gets part of what your customers pay: a content owner, an affiliate, a partner. You decide which products they share in and how much; each payment of those products is split when it is paid, and the payee's part is added to their balance. Payouts then send balances to the payees.
- The money is yours until it is paid out: customers pay your provider account, and payouts come from your own Stripe or PayPal account. The platform charges nothing and never holds the money.
- Only owners add payees, change shares and move money. Finance viewers can read balances, batches and statements. Admins do not see payouts.
Add a payee#
Payees → New payee: name, e-mail address and how they are paid.
| Paid by | What happens |
|---|---|
| Stripe transfer | The payee sets up an account at your Stripe (you must turn on Connect first, see Paying payees with Stripe). Payouts are Stripe Transfers from your Stripe balance; Stripe pays the payee's bank on their own schedule. |
| PayPal payout | Sent through your PayPal Payouts to the PayPal address you enter (the e-mail, unless you give another). See Paying payees with PayPal. |
| Paid by you (off-system) | You pay by wire, cheque or anything else and record it here. Note how you pay them; only you see it. |
Tick E-mail the payee an invitation and they receive a link to set a password for their earnings page in your customer portal (the link works for 3 days; afterwards Forgot password works). There they see their balance, every entry, payouts and monthly statements. A payee cannot change where money goes themselves: they send a change request (below).
If somebody registered the payee's address in your portal without ever confirming it, the invitation resets that account and only the owner of the mailbox gets in.
Change requests#
From their earnings page a payee can ask to be paid another way — a new PayPal address, Stripe, or paid by you with new details. They confirm with their password. Owners get an e-mail, Payouts shows how many requests wait, and the payee's page shows the request next to what is on file now.
- Approve applies it exactly like editing the payee yourself (and is recorded in the audit log). Reject changes nothing. Either way you can add a note; the payee is e-mailed with it.
- Payouts already queued or on their way keep the old destination; the next batch uses the new one.
- A new request from the same payee replaces one still waiting; the payee can also withdraw it.
Treat an unexpected request with care — if in doubt, confirm with the payee by a channel you already trust before approving.
Tax forms#
A payee can fill in a W-9, W-8BEN or W-8BEN-E on their earnings page. The payee's page shows the current form with the tax number masked (last four digits). Show the whole number asks for your password, and each reveal is recorded in the audit log. Earlier forms are kept, marked superseded. To make every live payout wait for a form, tick Require a tax form before paying in Payouts → Settings; the payee is then listed under Not in this batch. Test batches never ask.
The certification wording follows the IRS forms in plain language; it is not legal or tax advice — have your accountant confirm the forms suit you.
Statuses#
| Status | Meaning |
|---|---|
| Onboarding | The route is not ready: no Stripe account yet, or Stripe has not enabled transfers to it. Earnings still collect. |
| Active | Can be paid. |
| Disabled | You paused the payee: no share of new payments, no payouts. The balance stays and can be paid when you enable them again. |
Give a payee a share#
Open the product (Products → the product) and scroll to Revenue share. One row per payee:
- Percent of each payment, in steps of 0.01 % — at most 100 % in total; or
- Fixed USD per payment;
- Priority — shares are applied lowest number first.
Each share is capped at what is left of the payment, so the shares never add up to more than the payment: if a price cannot cover all fixed amounts, the payees last in priority get less (the panel warns you, and shows what a payment at the product's first price gives each payee).
The base is the payment's gross amount; provider fees stay with you. Subscription renewals are split like first payments.
Changes apply to payments from now on. Each payment keeps the shares it was split with when it was first paid — removing a rule never takes money back from earlier payments. To correct a balance, use an adjustment on the payee's page.
Refunds and disputes#
A payee's part of a payment follows the payment:
- Refund — reversed in proportion: refund a quarter and the payee loses a quarter of their share; a full refund reverses it all.
- Dispute (chargeback) opened — the whole share is held back (a reversal).
- Dispute won — restored.
- Dispute lost — stays at nothing.
If the payee's share was already paid out, the reversal makes the balance negative; the next earnings pay it off before anything else is sent (see Payouts).
Test mode#
Payments made with a Test credential set create test money: it shows under Test mode on the payee and payout pages and never mixes with live balances. Use it with a Stripe test account or the PayPal sandbox to rehearse a payout.
Payouts, the ledger and statements
Every payee has a ledger: a list of entries that is only ever added to. Their balance is the sum:
balance = earnings − reversals − payouts + returned payouts ± adjustments
| Entry | When |
|---|---|
| Earning | A payment they share in is paid (or a won dispute restores it). |
| Reversal | That payment is refunded or disputed. |
| Payout | Their balance goes into a batch. |
| Payout returned | A payout failed, was returned, or you withdrew it — the money is back. |
| Adjustment | You add or deduct an amount by hand, with a note the payee sees. |
Nothing is ever edited or deleted. A mistake is corrected with a new entry, so a statement printed last month still adds up today. The self-check verifies the ledger every day.
The hold period#
An earning becomes available a number of days after the payment (Settings → Hold, 7 by default), so most refunds and disputes arrive before money leaves. Until then it is on hold. A refund of money still on hold reduces the held part.
Negative balances#
If a payment is refunded after the payee's share was paid out, the reversal takes the balance below zero. Nothing is clawed back from the payee's account; their next earnings pay off the negative part first, and only what remains is paid out.
Build and send a batch#
Payouts → Build a batch takes every payee whose available balance reaches the minimum payout and whose route can pay, and reserves those amounts at once (they leave the available balance, so they cannot go into a second batch). Payees that cannot be paid are listed under Not in this batch with the reason — below the minimum, no Stripe account yet, no funding account chosen — and keep their balance.
Check the batch, then press Send. Nothing moves before that. Withdraw puts every amount back.
Text description
A batch is Scheduled, then Building while every available balance that reaches the minimum becomes a payout. A Ready batch waits for an owner to press Send, or is withdrawn (Canceled) and its money goes back. Executing: each payout is Queued, then Sent to Stripe or PayPal, then Paid; a payout can end Failed or Returned, which gives its money back to the payee's balance. A payout you make yourself stays Queued until you record it as Manual paid. When every payout has ended the batch is Completed (all paid), Partial (some not paid) or Failed (none paid).
- Stripe — one Transfer per payout from your Stripe balance. Accepted transfers are Paid at once. If you later reverse a transfer in Stripe, the reversal is booked from the webhook — and, should a webhook be missed, the system also re-reads each paid transfer once a day for 30 days. If your Stripe balance cannot cover it, the payout fails and its money returns to the payee's balance; add funds or wait for your Stripe balance to become available, and the next batch takes it.
- PayPal — one PayPal payout batch. Items are Sent, then Paid when PayPal confirms. Unclaimed items (the address has no PayPal account yet) stay Sent until claimed; after 30 days PayPal returns them (Returned, money back). Not waiting? Press Cancel unclaimed on the batch page: PayPal cancels the item at once, the payout is Returned and the money is back on the payee's balance (recorded in the audit log). Only unclaimed items can be canceled.
- Paid by you — stays Queued. Pay the payee, then enter how (cheque number, wire reference) and press Record paid. The payee is e-mailed.
A provider that cannot be reached leaves the payout Queued; the system tries again every 15 minutes with the same request (so it is never paid twice) and marks it Failed after five attempts.
The batch ends Completed (all paid), Partial (some not paid) or Failed (none paid). Owners are e-mailed when payouts fail.
Settings#
Payouts → Settings (owners):
- Stripe account — your own Stripe credential set that is the Connect platform for your payees. PayPal REST app — your own PayPal set whose Payouts API sends. Sets connected through the platform cannot fund payouts.
- Hold, Minimum payout.
- Batches — by hand, weekly (weekday) or monthly (day 1–28), UTC. A scheduled batch is built on that day; owners get an e-mail and press Send, unless Send scheduled batches automatically is ticked.
- E-mail payees their monthly statement — on the 1st of each month, for the previous month. A payee can opt out on their earnings page.
- Require a tax form before paying — live payouts wait until the payee has a W-9 or W-8 on file.
- Allow sending payout batches over the API — off by default: API keys can build, read and withdraw batches, but only someone signed in can send unless you tick this.
- 1099 threshold from 2027 — the tax summary uses $600 for 2025 and earlier and $2,000 for 2026; enter the amount for 2027 and later once the IRS publishes it.
Add the payout webhook events listed on the settings page to each funding set's webhook, so payouts update within seconds.
Statements#
Each payee page lists months with activity. A statement shows the opening balance, the month's entries by kind and the closing balance (closing = opening + the month's entries), as a page, PDF (US Letter, every entry, "Page n of N") or CSV. Exports has the whole ledger and every payout as CSV.
Tax forms#
The system collects W-9 / W-8BEN / W-8BEN-E forms from payees (see Payees) and adds up what each was paid, but it does not file forms.
Payouts → Tax summary lists, for a calendar year, every payee paid that year: the form on file, the masked tax number, what was paid by route (by date paid; returned payouts do not count and transfer reversals are subtracted) and whether the total reaches the year's 1099 threshold. CSV gives the same with masked numbers; Export with full tax numbers asks for your password and is recorded in the audit log. Owners and finance viewers see the summary; only owners export full numbers.
- In the United States, payments to independent contractors and royalties above the IRS thresholds may need a 1099 form from you; collect a W-9 from US payees before paying them (a W-8BEN from foreign payees).
- For payees paid through Stripe, Stripe can collect tax details and issue 1099s for your platform if you turn on Stripe Tax Reporting for Connect in your Stripe Dashboard.
- PayPal may issue its own forms to recipients who receive enough through PayPal; that does not replace forms you owe as the payer.
Ask your accountant which forms apply to you. The tax summary, the statements and the ledger export give them the figures.
Payouts over the API#
Owner API keys with write access can build a batch (POST /api/v1/payout-batches), read it, and withdraw it; sending (POST /api/v1/payout-batches/{id}/send) is refused with api_send_disabled unless Settings allows it. GET /api/v1/tax-summary?year= returns the summary with masked numbers. See the API reference.
Payments and their statuses
Transactions lists every payment, newest first. Search by confirmation code, email or provider id, and filter by product and status.
Statuses#
Text description
A payment starts as Created, then Pending while the buyer is on the provider's page. From Pending it becomes Paid, Failed, Canceled or Expired. Bank payments (ACH, eCheck) go from Pending to Processing for 3 to 5 business days, then to Paid or Failed (returned). A paid payment can become Partially refunded and then Refunded. A paid payment with a chargeback becomes Disputed; a won dispute returns it to Paid (flagged), a lost one makes it Chargeback.
| Status | Meaning |
|---|---|
| Created, Pending | Checkout started; the buyer is on (or left) the provider's page. |
| Processing | A US bank payment (ACH/eCheck) clearing, 3–5 business days. |
| Paid | Confirmed by the provider's signed webhook. Has a confirmation code. |
| Failed | Declined, or a bank payment returned. |
| Canceled, Expired | The buyer left, or the checkout timed out. Nothing was charged. |
| Partially refunded, Refunded | Some or all of the amount went back. |
| Disputed | The buyer's bank opened a chargeback; see Disputes. |
| Chargeback | The dispute was lost; the money went back to the buyer. |
A payment's page#
- Amount, Fee / net — the provider's fee and what you receive. Authorize.net does not report fees, so its net equals the gross.
- Provider ids — the ids to look the payment up in the provider's dashboard.
- Buyer note — the optional note from the pay page.
- History — every status change, with its source: webhook, admin, customer or system.
- Refund requests, Refunds, Disputes — anything that happened after the payment.
Refunding from the admin side#
Owners and admins can refund any paid payment, whatever the product's policy says:
- Enter an amount, or choose Refund everything.
- Add an internal reason.
- Refund. The refund is sent to the provider; the payment becomes Partially refunded or Refunded when the provider confirms it.
Authorize.net can only void a payment that has not settled yet (usually the same day), and only in full. After settlement, partial and full refunds work.
Offline payments#
On a customer's page, Record offline payment enters a payment received outside the providers, for example by cheque or bank transfer. It gets a confirmation code and grants access like any other payment, and the reason is kept with it.
Customers and access
Customers lists everyone who paid, subscribed, holds a plan, or created an account. Admins limited to some products see only those products' customers.
A customer's page#
- Access by product — for each product: free, paid (until when) or complimentary, and the state of the access.
- Payments, Subscriptions, Licenses — everything of this customer in one place.
- Access history — when access was granted, changed or ended, and by whom.
Changing access#
| Action | What it does |
|---|---|
| Grant complimentary | Paid-level access without payment, optionally until a date. Use for partners, press or support cases. |
| Give free plan | Puts the customer on the product's free plan. |
| Email upgrade link | Sends the customer a link to the pay page of a paid plan. |
| End paid access | Ends complimentary or offline access now. Subscriptions are canceled from the subscription itself. |
| Record offline payment | Enters a payment received outside the providers; see Payments. |
Every change is written to the audit log.
Registered, but not confirmed#
The customer list shows registered or registered, verified. Anyone can register an address they do not own, so an unconfirmed account is not trusted with anything it did not buy in its own session. When you grant access or record an offline payment for such an account, when your API key creates a checkout for its address, or when somebody pays for that address without signing in, the account's password is removed and its devices are signed out. The customer sets a new password with the emailed link (Create an account or Forgot your password?). The audit log records this as customer.unverified_password_removed. Confirmed accounts are never touched.
Managing a subscription for the customer#
Next to each subscription, Manage offers the same actions the customer has, plus Cancel now where the provider supports it. See Subscriptions.
Subscriptions
Text description
A subscription starts Incomplete until the first payment or trial is confirmed, then becomes Trialing or Active. Active subscriptions renew each period. A failed renewal makes it Past due while the provider retries; a later success returns it to Active, otherwise it ends as Unpaid or Canceled. An active subscription can be Paused and resumed. Cancellation happens immediately or at the end of the paid period. A plan change waits as pending and takes effect at the next renewal.
What each provider supports#
| Action | Stripe | PayPal | Square | Authorize.net |
|---|---|---|---|---|
| Cancel at period end | yes | yes (billing stopped now, access kept) | yes | yes (billing stopped now, access kept) |
| Cancel now | yes | yes | — | yes |
| Pause / resume | yes | yes | yes | — |
| Change plan (same interval, next renewal) | yes | yes (buyer approves) | yes | yes |
| Retry a failed payment now | yes | yes | — (Square retries itself) | — |
Each action calls the provider first. The provider's webhook then moves the status, and the customer is emailed.
Renewals and failed renewals#
- A successful renewal creates a new payment with its own confirmation code.
- A failed renewal makes the subscription Past due. The customer keeps access for a 3-day grace period while the provider retries. After that, access pauses until a payment succeeds, or the subscription ends as Unpaid or Canceled, depending on the provider's retry settings.
- Plan changes requested by you or the customer wait as pending and take effect with the next renewal, without proration.
Where to find subscriptions#
On each customer's page, and in the subscriptions export (Exports). The Analytics screen shows MRR, active, trialing and past-due counts, and churn.
Refund requests
Customers ask for refunds in their account. Every request is checked against the product's refund policy, set on the product under Refunds.
Text description
A customer's refund request is checked against the product's refund policy. If every check passes it is Auto-approved and Executing at once: the refund is sent to the provider, and the request is Completed when the provider confirms, or Failed. If a policy check fails it goes to Pending review; an owner or admin approves it (the amount may be lowered), which moves it to Approved and Executing, or denies it with a note to the customer. A dispute on the payment closes open requests as Superseded by dispute.
The checks#
| Check | Fails when | Then |
|---|---|---|
| Status | the payment is not Paid or Partially refunded | refused |
| Amount | zero, or more than is still refundable | refused |
| Dispute | a dispute is open on the payment | refused |
| Window | the payment is older than the refund window | review |
| Mode | refunds are off, or only full refunds are allowed and the amount is partial | review |
| Count | the customer reached the yearly limit | review |
| Period | a subscription charge whose period ended or was replaced by a later charge | review |
When every check passes, the request is approved automatically and the refund goes to the provider at once. It completes when the provider confirms it.
Deciding a request#
Refund requests shows the requests that need a decision first. Owners and admins are emailed for each one, unless they turned that notification off. Open a request to see which checks failed and the customer's reason.
- Approve — you may lower the amount. The refund is sent at once.
- Deny — write a short note. It is emailed to the customer, so keep it plain and specific.
A dispute opened on the payment closes its open requests as Superseded by dispute.
Disputes and evidence
A dispute is opened by the buyer's bank, not by the buyer through your store. It arrives by webhook from Stripe, PayPal or Square. Authorize.net does not send dispute notifications; handle those in its Merchant Interface.
Text description
A chargeback opens as Opened and moves to Evidence due; after you submit evidence it is Submitted and ends Won or Lost. An inquiry may close without money moving, or escalate into an opened chargeback. A fraud warning moves no money: refunding the payment usually prevents a chargeback, and the warning is then closed.
The Disputes screen#
Open cases are listed with the soonest evidence deadline first. Due soon marks deadlines within 3 days. Owners and admins are emailed when a dispute opens, with its deadline.
| Kind | Money moved? | What to do |
|---|---|---|
| Chargeback | Yes: the amount is held back | Submit evidence before the deadline |
| Inquiry | No | Answer the questions; it may close or escalate into a chargeback |
| Fraud warning (Stripe) | No | Usually refund now: a refund costs less than a lost chargeback |
What evidence to gather#
Good evidence answers the bank's reason code directly. Collect only what applies:
- Proof of purchase — the receipt, the confirmation code, the date and the product.
- Proof of delivery or use — download logs, license check-ins (the license's machine list), sign-in history, shipping tracking.
- Communication — emails with the buyer, especially any where they confirm the purchase or the problem was solved.
- Your policies — the terms and refund policy as shown at the time of purchase, and that the buyer accepted them.
- For "canceled subscription" claims — the dates the subscription was active and that it was not canceled before the charge.
Write a short, factual note that ties the files to the reason. Avoid emotion and long histories.
Adding and submitting evidence#
On the dispute's page:
- Add files — PDF, PNG, JPEG or plain text, up to 5 MB each. The type is checked from the content, not the file name. Files are stored privately and only your workspace can download them.
- Add notes.
- Submit:
- Stripe: the notes, the customer's email, the product description and the first file are sent through the API in one submission. Submit once you have everything; Stripe accepts one submission.
- PayPal and Square: submit in the provider's dashboard, then press Submit here to record it, so the case is tracked.
When the provider decides, the case becomes Won (the payment returns to Paid, flagged) or Lost (the payment becomes Chargeback and paid access ends).
Keeping disputes rare#
- Use a clear product name and description; the store name appears on the buyer's statement.
- Answer support email quickly and refund when a buyer is unhappy.
- Watch the dispute rate on Analytics: the alert threshold is 1.0%, with a warning at 0.75%.
Discount codes
Discount codes creates codes that buyers type on the pay page. The pay page shows a code field as soon as your workspace has at least one active code.
Creating a code#
| Field | Rules |
|---|---|
| Code | Letters and digits; buyers type it in any letter case. |
| Type and value | Percent (1–100, rounded down to the cent) or a fixed amount. |
| Applies to | Every plan, one-time payments only, or subscriptions only. |
| Products | None ticked means every product. Admins limited to some products must pick their own products. |
| Limits | Total uses, uses per customer (by email), start date, end date (UTC days). |
The code, type and value cannot change after creation, because customers may already hold the code. To change a discount, archive the code and create a new one.
What the buyer is charged#
- The provider charges the discounted amount. The total must stay at least $0.50.
- On a subscription, the discounted price becomes the subscription's price: every renewal is discounted. A later plan change bills the new plan's normal price.
- With a quantity, the order becomes one discounted line at the provider, for example "Pro × 3 (SPRING)".
How uses are counted#
- A use is held when a checkout starts. Holds count toward the limits for one hour.
- It is redeemed when the payment is confirmed, or when a subscription or free trial starts.
- It is released if the checkout fails, is canceled or expires.
Delete works only for a code that nobody used. Otherwise archive it, so payment history keeps its name.
Payment links
A payment link opens a checkout for one product plan. Send it to a buyer by email or chat when you agree a price or want to invoice someone.
Options#
- Price override — for one-time plans, at least $0.50.
- Only for this customer — locks the link to an email address. The receipt always goes to that address.
- Discount code applied automatically.
- Message shown on the link's page and in the email.
- Number of payments allowed — 1 by default; empty means unlimited.
- Expiry date.
Sending and following a link#
The link's page shows the address to copy (/pay/link/…), a form to email it, and every checkout opened from it with its result.
- Link pages are never indexed by search engines and never cached.
- While one buyer's checkout from a single-use link is open (up to an hour), other buyers wait. The same buyer may retry.
- A use is counted when the payment is confirmed. A single-use link then becomes Used.
- Revoke ends a link at once. Expired and revoked links tell the buyer so plainly.
Analytics and insights
Analytics shows your numbers as charts and tables; Insights writes the findings in plain sentences with recommendations. Both use only your own payments and your own pay-page visits.
Financial figures#
| Figure | How it is counted |
|---|---|
| Gross | Paid amounts, on the day they were paid (UTC). |
| Fees, Net | The provider's fee and gross minus fee. Authorize.net reports no fees: its net equals gross and is marked. |
| Refunds, Disputes | Refunded amounts and disputed amounts, on the day they happened. |
| MRR, ARR | Monthly recurring revenue of active subscriptions, normalised to a month (quarterly ÷ 3, annual ÷ 12), and MRR × 12. |
| Active, trialing, past due | Subscriptions at the end of each day. |
| New, churned | Subscriptions that started or ended that day. |
| Recovery rate | Failed renewals later paid, as a share of failed renewals. |
| LTV | Average revenue per customer of a product. |
| Cohorts | Customers grouped by the month of their first payment, and how many still pay in each later month. |
Refund rate and dispute rate are shares of paid payments. The dispute rate warns at 0.75% and alerts at 1.0%, the levels at which card networks start to watch a merchant.
Site analytics#
Visits to your store and product pages are counted without cookies: visitors are recognised only within one day, through a daily-changing hash, and no IP address is stored. You see views, unique visitors, referrers, campaigns (UTM), devices, countries and cities, and the funnel per product: product page → pay page → checkout started → paid. Bots are left out.
Charts#
Every chart has a hover tooltip, keyboard focus and a data table under Show data. PNG downloads the chart as an image, for reports and email.
Insights#
The insights compare periods, fit a trend with a 30-day forecast, flag unusual days, show how much revenue depends on a few products, check each product's refund and dispute rates against the thresholds, and measure churn, free-to-paid conversion and lifetime value. Every recommendation shows the numbers it is based on. The weekly digest email carries the same findings.
Exports and the audit log
Exports#
Exports downloads CSV files for a UTC date range and, optionally, one product.
| Kind | Who |
|---|---|
| Payments, customers, subscriptions, refunds, disputes | Owners, admins (their products), finance viewers |
| Discount-code uses | Owners and admins |
| Audit log | Owners |
The files open correctly in Excel and other spreadsheets: UTF-8 with a byte-order mark, money as plain decimals (1234.56), at most 100,000 rows. Any cell that begins with =, +, - or @ is prefixed with an apostrophe, so a spreadsheet never runs it as a formula. Every export is recorded in the audit log with its filters and row count.
The audit log#
Settings → Audit log (owners) lists every change in the workspace: who did it, when, from which IP address, and the values before and after.
- Filter by who (member, customer, system, platform admin), action, text (email, id, IP), date range.
- Open an entry for a field-by-field comparison.
- Actions by the platform operator appear as Platform admin, including anything done while acting as one of your members. The log cannot be edited or deleted, not even by the database user the application uses.
Members, roles and signing in
Settings → Members (owners) invites people and sets their role.
Roles#
| Can… | Owner | Admin | Finance viewer |
|---|---|---|---|
| See the overview, payments, customers, analytics, exports | yes | yes | yes |
| Manage products, discount codes, payment links | yes | yes | — |
| Refund, decide refund requests, handle disputes, manage subscriptions | yes | yes | — |
| See gateways | yes | yes | — |
| Add or change gateways, branding, members; see the audit log | yes | — | — |
| API keys and webhooks | yes | yes (with access to every product) | — |
Limiting an admin to some products#
Product access for admins gives an admin either all products (the default) or only selected products. A limited admin sees only those products and their payments, customers, refund requests, disputes, subscriptions, codes, links and exports. Pages for anything else answer Not found, so they cannot tell it exists. Products they create are added to their selection. Changing their access signs them out everywhere.
Signing in#
- Invitations arrive by email and are valid for a limited time. Accepting one sets your password.
- Forgot your password? sends a reset link, valid once for 30 minutes.
- After 5 wrong passwords in 15 minutes the account is locked; the email we send contains an unlock link.
- Sessions end after 30 minutes without activity, and after 12 hours in any case.
- With two-step sign-in, a code from your authenticator app follows the password. See Two-step sign-in and security settings.
Your profile#
Profile (your name at the bottom of the menu) changes your password and lists your signed-in devices. Sign out one device or every device. Changing your password signs out your other devices.
Two-step sign-in and security settings
With two-step sign-in, a password alone no longer opens your account: after the password, every sign-in asks for a 6-digit code from an authenticator app on your phone. Codes change every 30 seconds and each one works once.
Setting it up for yourself#
- Open Profile (your name at the bottom of the menu), then Two-step sign-in → Set up.
- If you have no authenticator app yet, install one. Any app that supports time-based codes works: 1Password, Bitwarden, Google Authenticator, Microsoft Authenticator, Authy and others.
- Scan the QR code with the app. If you cannot scan, add the account by hand with the set-up key shown under the code (time-based, 6 digits, 30 seconds).
- Type the code the app shows and press Turn on.
- Save your ten recovery codes. They are shown once. Each one signs you in once instead of a code, for the day you lose your phone. Print them or keep them in your password manager.
You get an email whenever two-step sign-in is turned on or off for your account, when a recovery code is used, and when new codes are made.
Signing in with two-step sign-in#
After your password, type the code from the app. No phone? Type one of your recovery codes in the same field (like abcde-fghjk).
- Five wrong codes end the attempt: sign in again with your password.
- Ten wrong codes for one account within an hour pause code entry for the rest of the hour, whatever the number of sign-ins, and the account holder is emailed: whoever tried knows the password, so change it.
- Wrong codes also count as failed sign-ins, so the usual pause and unlock email apply.
New recovery codes, turning it off#
On Profile → Two-step sign-in:
- Create new codes replaces all ten codes (confirm with a code from the app).
- Turn off two-step sign-in needs your current password and a code. It is not offered when your workspace requires two-step sign-in.
Requiring it from every member#
Owners: Settings → Security → Require two-step sign-in from every member.
- Turn it on for yourself first; the setting refuses otherwise.
- Members who have not set it up are signed out at once. At their next sign-in they set it up before they can open anything; new members do the same when they accept their invitation.
- The members table shows who has it (On) and who will set it up (At next sign-in).
A member lost phone and recovery codes#
Owners: Settings → Security, find the member, Reset. Their two-step sign-in is turned off, every session they have ends, their recovery codes stop working, and they are emailed. The audit log records who reset it. If the workspace requires two-step sign-in, they set it up again at their next sign-in.
An owner cannot reset their own two-step sign-in here; another owner can, or the platform administrator from the command line.
How customers register#
Settings → Security → Customer registration decides what the Create an account form does:
| Mode | What the customer does | What a visitor can learn |
|---|---|---|
| Private (default, recommended) | Gives name and email, gets "check your email", opens the link and chooses a password there. | Nothing: the page is the same whether the address has an account or not. The email says which case it is: a link to finish, a link to set a password for earlier purchases, or "you already have an account" with sign-in and reset links. |
| Instant | Chooses a password on the form and is signed in at once; confirms the address later. | Typing an address that has an account answers "you already have an account". |
With private registration, a free plan chosen on the registration page starts when the customer opens the link and sets the password. An address receives at most three registration emails per hour.
Form tokens#
Every form carries a token. When you are signed in, the token is derived from your session: a form copied from another session, or a token planted in a cookie, is refused. If a form says Your session form token expired, reload the page; this happens after you signed out and in again in another tab.
Branding and policies
Settings → Branding & policies (owners) controls how your pay pages, customer account pages and customer emails look.
| Setting | Rules | Where it appears |
|---|---|---|
| Accent colour | #rrggbb; white button text must keep a contrast of at least 4.5:1, so very light colours are refused | Buttons and the main figure on pay and account pages, social preview images |
| Logo | PNG, JPEG, WebP or GIF, up to 512 KB, 16–2000 px; SVG is refused because it can carry script | Pay and account pages, about 32 px tall |
| Support email | — | Pay page footer; Reply-To of every customer email |
| Receipt and email footer | Plain text, up to 500 characters | After every customer email |
| Refund defaults | Window, full/partial/none, yearly limit | Prefilled in new products |
| Terms, privacy, refund policy | Plain text, blank lines make paragraphs, up to 20,000 characters each | /pay/<workspace>/legal/terms (and privacy, refunds), linked from every pay page |
Writing your policies#
- Say plainly what you sell, how long refunds are possible, and how buyers reach you.
- Keep the refund policy text consistent with the product settings: the settings decide automatic approval, the text explains it.
- Policy pages are public and indexed by search engines, so buyers can find them before they pay.
Notifications
Settings → Notifications — every member chooses their own emails:
- every payment;
- payments at or above an amount you set;
- failed payments;
- completed refunds;
- disputes and fraud warnings;
- refund requests that need a decision;
- a daily summary, sent after 12:07 UTC, covering yesterday (UTC): payments, gross, fees, net, failures, refunds, disputes, requests awaiting a decision, and the top products.
Until you save your own choices, owners and admins receive disputes and refund reviews, and finance viewers receive nothing. Admins limited to some products hear only about their products.
API keys and outbound webhooks
Settings → API & webhooks is for owners and admins with access to every product. The complete reference, generated from the routes and with a "try it" console, is at /api/docs.
API keys#
- Read keys can list and read. Read and write keys can also create checkouts, refund, record offline payments and manage webhooks.
- A key can be limited to some products, to IP addresses (one address or CIDR per line) and to an expiry date.
- The key is shown once, when you create it. Store it in your server's secret store; only a fingerprint is kept here.
- Requests send
Authorization: Bearer bk_…. Each key may make 600 requests per minute (X-RateLimit-*headers;429withRetry-Afterbeyond that). - Errors are JSON problem documents with a stable
code. POST requests accept anIdempotency-Keyheader, so a retried request never charges or refunds twice. - Renaming a key, changing its products or addresses, and revoking it are all recorded in the audit log.
| Area | Endpoints |
|---|---|
| Key | GET /me |
| Products | GET/POST /products (create with plans), GET/PATCH /products/{id|slug}, POST /products/{id}/plans, PATCH /products/{id}/plans/{plan} (archive/activate) |
| Checkouts | POST /checkouts → {url, checkout_id, checkout}; GET /checkouts/{id} |
| Transactions | GET /transactions (status, kind, provider, product, customer, subscription, email, created/paid from/to); GET /transactions/{id} (with refunds); GET /transactions/by-code/{code}; POST /transactions/{id}/refund (full when amount is left out); POST /transactions/manual (offline payment: grants access, issues a license, sends the receipt) |
| Access | GET /paid?email=|customer_id=|code=&product= → {paid, level, valid_until, subscription_status, last_transaction} |
| Customers | GET /customers (email, created from/to); GET /customers/{id} (with access per product) |
| Subscriptions | GET /subscriptions, GET /subscriptions/{id}, POST /subscriptions/{id}/cancel ({"at_period_end": true} default) /pause /resume |
| Payment links | GET/POST /payment-links, GET /payment-links/{id}, POST /payment-links/{id}/revoke |
| Webhooks | GET/POST /webhooks, GET/PATCH/DELETE /webhooks/{id}, POST /webhooks/{id}/test, POST /webhooks/{id}/rotate-secret, GET /webhooks/{id}/deliveries, POST /webhooks/{id}/deliveries/{d}/redeliver |
| Analytics | GET /analytics/summary?range=7d|30d|90d|12m|mtd|ytd|custom&from&to&product |
| Licensing | GET /licenses, GET /licenses/{id}, POST /licenses/{id}/{suspend|resume|revoke|seats|regenerate|expires}, DELETE /licenses/{id}/instances/{instance}, POST …/instances/{instance}/{block|unblock|remove}, GET/POST /products/{id}/signing-keys, POST /products/{id}/signing-keys/{kid}/{activate|retire}. These are the same handlers as the session-based /admin/api/licenses… (LICENSING.md), and the key's product scope applies. |
Checkouts created through the API do not record the caller's IP or country, because the caller is your server, not the buyer. The buyer still pays on the provider's hosted page.
Add endpoints on the settings screen or with POST /webhooks. A workspace can have up to 20. The signing secret (whsec_…) is shown once. Each endpoint subscribes to chosen events or to all events (*, which includes events added later).
| Event | When |
|---|---|
payment.paid | A purchase, a subscription's first or renewal charge, or an offline payment. |
payment.failed | A payment attempt failed. |
payment.refunded | A full or partial refund was confirmed. |
subscription.started | A subscription began (trialing or active), including no-card trials. |
subscription.renewed | A renewal charge succeeded. It arrives together with payment.paid. |
subscription.past_due | A renewal charge failed. |
subscription.canceled | The subscription ended. |
subscription.paused | The subscription was paused. |
subscription.resumed | A paused subscription resumed. |
subscription.plan_changed | A requested plan change took effect, at the renewal. |
dispute.opened | A dispute, inquiry or fraud warning opened. |
dispute.closed | A dispute was won, lost or closed. |
ping | Test sends only. |
Request
POST <your url>
Content-Type: application/json
Billing-Event: payment.paid
Billing-Event-Id: evt_01J…
Billing-Delivery: 01J…
Billing-Signature: t=1793000000,v1=5f0c…
{"id":"evt_01J…","object":"event","type":"payment.paid","api_version":"v1","created":1793000000,"tenant":"acme",
"data":{"object":{ …the transaction, subscription or dispute, as the API returns it… }}}
Checking a delivery. v1 = hex(HMAC-SHA256(secret, t + "." + raw body)). Compare in constant time, and reject a t more than 5 minutes away from your clock:
preg_match('/t=(\d+)/', $_SERVER['HTTP_BILLING_SIGNATURE'], $t);
preg_match('/v1=([0-9a-f]{64})/', $_SERVER['HTTP_BILLING_SIGNATURE'], $v);
$raw = file_get_contents('php://input');
$ok = abs(time() - (int) $t[1]) <= 300 && hash_equals(hash_hmac('sha256', $t[1] . '.' . $raw, $secret), $v[1]);
Answering
- Answer with any 2xx within 10 seconds.
- Do slow work after answering.
- Use
Billing-Event-Idto ignore repeats: the same event can arrive twice, after a timeout or a redelivery.
Retries. A failed attempt (no answer, a timeout, or a non-2xx status) is retried 1 min, 5 min, 30 min, 2 h and 12 h later. That is 6 attempts over about 15 hours. Then the delivery is marked failed and the workspace owners get one e-mail per endpoint per day. Each delivery's attempts, last status, error and the start of your answer are on the endpoint's page, where you can Send again. Send a test event sends a ping immediately and shows the result.
Security
- Endpoints must be
https://and public. At creation, and again at every send, the host is resolved, and loopback, private, link-local, carrier-grade NAT and reserved addresses are refused. - The connection is pinned to the checked address, so DNS rebinding does not work. Redirects are not followed.
- For lab setups,
'api' => ['webhooks' => ['allow_private' => true, 'allow_http' => true]]indata/config.phplifts these two rules. These settings are not available on any screen.
Delivery job. The webhooks.deliver job runs every minute. On a cluster it runs on the writable node only. Delivered events are kept 30 days (api.prune).
Licensing (software products)
Software sold through the platform runs with a license key. The program asks the platform for a signed lease every few minutes and keeps serving only while it holds a valid one. When you disable the customer or the product, or payment stops, the program stops within one check interval; it resumes by itself when the problem is fixed.
Licensed Go binaries sold through billing. A customer gets a license key, downloads the binary and runs it with the key. The binary asks billing for a signed lease every few minutes. It keeps serving only while it holds a valid lease.
If you disable the customer or the product, or payment stops, the binary stops within one check interval. It resumes by itself once the problem is fixed: no restart, no new key.
The full specification is LICENSING-BILLING-v0.1.0.md (Part A). How it maps onto billing's tables is described in amendment v0.3.0 §H14. The Go side is the golicense package (LICENSING-GO-v0.1.0, a separate project).
Contents#
- Create a leased product
- Embed the key in the binary
- Publish a download
- How customers get a license
- What billing decides on every check
- Reading the instance list
- Managing a license
- Rotating a signing key — and a compromised key
- Admin JSON API
- Endpoints, limits and URL modes
- Jobs, self-check, storage
- Troubleshooting
1. Create a leased product#
Products → product → Licensing (owners and admins).
| Field | Meaning |
|---|---|
| Mode | None (an ordinary product) or Lease (a licensed binary). |
| Product code | Compiled into the binary, e.g. cacheproxy. 2–32 characters a-z 0-9 _ -, unique in the workspace. |
| Seats per license | How many machines may run one license at the same time (new licenses start with this value). |
| Lease TTL (s) | How long a copy keeps running with no contact. This is the offline grace period. Default 86400 (24 h); allowed 3600–604800. |
| Check every (s) | How often a copy checks in, so how fast a pause or a fix reaches it. Default 300; allowed 60–3600; must be below the TTL. |
| Past-due grace (days) | After a renewal fails, how long leases are still granted (with a warning) before service pauses. Default 3. |
| Features | Optional JSON object sent in every lease, e.g. {"max_tenants": 10, "http3": true}. A license can override single keys (API/DB field features_override). |
| Download file / Version | The build customers download (section 3). The version is sent to running copies as latest_version. |
Saving in Lease mode does three things:
- Creates signing key
k1(active). - Backfills licenses for customers who already have paid or complimentary access to the product.
- Shows the lease endpoint (with the URL form your server uses) and the trial status.
Offering a free trial. Add a recurring plan (monthly, quarterly or annual) with trial days. The pay page then shows Start free trial (no card) to signed-in customers.
2. Embed the key in the binary#
The Licensing panel shows a ready block for license_keys.go:
// license_keys.go — generated from the billing admin "Licensing" panel. Keep ≥ 1 key.
package main
const productCode = "cacheproxy"
var licensePublicKeys = map[string]string{
"k1": "3f1c…64 hex characters…",
}
Copy it into the product's repository. It holds only public keys; the secret halves never leave billing. They are sealed with the install's master key (data/keys/master.key).
3. Publish a download#
Choose one of two ways:
- Upload a build on the Licensing panel. It is stored in
data/downloads/<workspace id>/<code>/<file name>. Uploads are limited by PHP'supload_max_filesize/post_max_sizeand Nginx'sclient_max_body_size. - Copy the file to the server and enter its name in Download file. Use this for large binaries. The name is relative to
data/downloads/, for example3/cacheproxy/cacheproxy-1.4.2-linux-amd64. Path traversal is refused, and the file must exist.
Customers download from /account/<workspace>/download/<code>. They must be signed in and hold a license for the product that is not revoked. The file is streamed from outside the webroot as an attachment, 1 MB at a time.
4. How customers get a license#
One license exists per customer × product. Its key does not change when a trial becomes paid.
| Event | Result |
|---|---|
| Start free trial | A subscription with provider none (no card, no provider calls), status trialing, until trial_end. Paid access is granted for the trial, and a license is created. The license page opens with the key, the download and the run command. One trial per customer and product: a second attempt goes to checkout ("Trial already used"). The provider checkout of a customer who already had the no-card trial gets no second trial. |
| Subscribe (any provider) | The license is attached to the new subscription; the key is kept. The no-card trial is closed. |
| One-time purchase | A license without a subscription. It works while the purchase gives access: a full refund or chargeback ends it. |
| Offline payment (customer page) | Same as a one-time purchase; an end date set there caps the license. |
| Complimentary access (customer page) | A license, capped at the comp end date. Comp also keeps a license running when its subscription has ended. |
| A new purchase after a revoke | The license comes back with a new key. A renewal of the same subscription never undoes a revoke. |
When the trial ends. Leases are denied as soon as trial_end passes. Within 15 minutes the job licensing.trials closes the trial subscription, and access falls back (to Free if the product has a Free plan). Customers can also end a trial at once from their account page.
5. What billing decides on every check#
The checks run in this order; the first one that fails decides the reason.
| Reason | When |
|---|---|
unknown_key | No license has that key (wrong key, or replaced by Issue a new key). |
product_mismatch | The key belongs to another product code. |
product_disabled | The product is not in lease mode, not active, or deleted. |
disabled | The workspace or the customer is disabled, or the license is suspended. When suspended, your message is shown. |
revoked | The license was revoked. |
expired | The trial is over; the subscription was canceled (immediately, or after the paid period); it is paused or incomplete; or the license's own end date passed. |
unpaid | The subscription is past due beyond the grace period, or unpaid. |
seat_limit | A new machine while every seat is in use. Machines already counted are never refused for seats. |
instance_blocked | That machine was blocked. |
Grants. A grant is a signed lease with state: active, trialing (capped at the trial end) or past_due (capped at the grace end, with a warning message).
Messages. Denials carry a human message and a link to the customer's license page. The binary shows both on screen.
The paused-service email. The first unpaid or expired denial emails the customer (template license_paused), at most once per license per 24 hours.
6. Reading the instance list#
Each running copy is one instance: one machine, identified by a hash of its machine id. Columns:
- Host, plus the id and version.
- Last check, plus when it was first seen.
- IP and OS / client.
- Status:
- active: checking in and served;
- denied: checking in and refused; the reason is shown;
- released: shut down cleanly; its seat is free;
- stale: silent for more than 2 × the lease TTL; its seat is free;
- blocked.
Possible clone (same machine-id, different hostnames). The same machine id reported different host names within two check intervals, typically a cloned VM. It occupies one seat; machine-id binding cannot tell clones apart. Clones are flagged, not silently allowed. Block the instance, or ask the customer to reset the clone's /etc/machine-id.
Actions (customers can do these on their own licenses too):
- Remove frees the seat now. A removed copy that is still running takes a seat again at its next check.
- Block / Unblock stops or allows that machine.
7. Managing a license#
Licenses (menu) lists every license. Filter by product and status, or search by email, full key or the last 4 characters. A customer's page also has a Licenses section.
On the license page, owners and admins can:
| Action | Effect |
|---|---|
| Suspend (message) | Denied disabled with your message. |
| Resume | Served again at the next check. |
| Revoke | Denied revoked. |
| Seats | A reduction applies as copies go stale or are removed. |
| End date | A hard end date; empty means none. |
| Issue a new key | Every running copy is denied unknown_key until it is restarted with the new key. |
Permissions. Finance viewers can see licenses but not change them. Admins with product access limited to some products see only those products' licenses.
Super admins. Platform → Licenses lists the licenses of every workspace and can act on them. Their actions are logged as super:<id>.
Every action is recorded twice:
- in the license history, as
admin:<id>,customer:<id>orsuper:<id>; - in the audit log.
8. Rotating a signing key — and a compromised key#
Only the active key signs. Each leased product has exactly one active key. To rotate without a glitch:
- Create pending key (
k2). Its public key appears in the table and in the embed block. - Rebuild the product with both
k1andk2inlicense_keys.go, and roll the build out. - Activate
k2. In one step,k1is retired and its secret is erased; its public key stays for the record. Old builds that know onlyk1stop verifying from this moment, which is why step 2 comes first. - Drop
k1from the next build.
A compromised key. Do steps 1–3 as fast as the rollout allows. A forged grant can live at most one lease TTL. If the secret leaked together with the master key, also rotate the master key. That is out of scope here; see INSTALL.
9. Admin JSON API#
| Item | Detail |
|---|---|
| Authentication | Same session as the admin screens. Every POST and DELETE needs X-CSRF-Token, set to the value of the bcsrf cookie (__Host-bcsrf over HTTPS). Run 6 adds API keys. |
| Responses | JSON. Errors are RFC 7807 problem documents. |
| Keys | The license key is never returned; reveal it in the dashboard. |
| URL form | Clean URLs are shown. Plain vhosts use /admin/index.php?r=api/licenses…. |
GET /admin/api/licenses?customer_id=<pub>|product_id=<pub>|status=active|suspended|revoked|q=…
GET /admin/api/licenses/{id} license + instances + last 50 events
POST /admin/api/licenses/{id}/suspend {"reason":"…"}
POST /admin/api/licenses/{id}/resume
POST /admin/api/licenses/{id}/revoke
POST /admin/api/licenses/{id}/seats {"seats":5}
POST /admin/api/licenses/{id}/regenerate
POST /admin/api/licenses/{id}/expires {"expires_at":"2027-01-01T00:00:00Z"} or {"expires_at":null}
DELETE /admin/api/licenses/{id}/instances/{instance_id}
POST /admin/api/licenses/{id}/instances/{instance_id}/remove same as DELETE, for clients that cannot send DELETE
POST /admin/api/licenses/{id}/instances/{instance_id}/block or …/unblock
GET /admin/api/products/{id}/signing-keys keys + the license_keys.go block
POST /admin/api/products/{id}/signing-keys create a pending key
POST /admin/api/products/{id}/signing-keys/{kid}/activate or …/retire
{id} is the license's public id, as in its page URL. Super admins have the same license calls under /super/api/licenses…, across every workspace.
10. Endpoints, limits and URL modes#
The binary talks to two public endpoints. The license key is the credential: no session, no cookies, no CSRF.
| Endpoint | Clean URLs (front controller) | Plain PHP vhost |
|---|---|---|
| Lease | POST /api/v1/license/lease | POST /api/?r=v1/license/lease |
| Release (on shutdown) | POST /api/v1/license/release | POST /api/?r=v1/license/release |
The Licensing panel shows the exact lease URL of your server. Configure the binary's server URL to match. The production encrypted.com vhost uses clean URLs (nginx-hardened.conf).
Status codes:
- 200, always, for a well-formed request:
okwith a signed lease, ordeniedwith a reason. - 400 for a malformed request.
- 405 for anything but POST.
- 429 when rate-limited, with
retry_sin the body and aRetry-Afterheader. - 503 if the product has no usable signing key; the self-check reports this.
The client treats anything but a parseable 200 as "unreachable" and keeps running on its current lease.
Rate limits:
- Per IP: 120 lease/release calls per minute.
- Per key:
max(30, 2 × seats)per minute.
A whole fleet restarting at once is never throttled by its own size.
Behind a proxy or webgate. If a proxy or webgate sits in front of billing, make sure PHP sees the client address, or every binary shares the proxy's per-IP budget.
11. Jobs, self-check, storage#
Jobs:
licensing.trials(every 15 min) closes no-card trials whosetrial_endpassed.licensing.maintenance(daily 03:53 UTC) deletes instances unseen for 90 days and license events older than 365 days.
Self-check:
- "Leased products can sign leases" fails if an active leased product has no active key.
- "Leased products have a download" warns if an active leased product has no file.
Storage:
- Tables:
licenses,license_instances,license_events,product_signing_keys, plus licensing columns onproducts. - Keys are stored as a SHA-256 hash for lookup, plus a sealed copy for the dashboard Reveal.
- IP addresses are stored in binary form.
- Downloads live in
data/downloads/.
Interop check (per release). app/tests/fixtures/envelope.json is an envelope signed over real Nginx, and envelope.pub is its public key. Verify them with Go's standard library:
go run app/tests/interop/verify_envelope.go app/tests/fixtures/envelope.json app/tests/fixtures/envelope.pub
The golicense repository's lictest -verify-file command does the same.
12. Troubleshooting#
| Symptom | Look at |
|---|---|
| A copy says "license key not recognised" | The key was replaced (Issue a new key) or mistyped. Copy it again from the license page. |
| "All N seats in use" | The instance list: remove old machines, or raise the seats. |
| Everything answers 503 | Self-check, "Leased products can sign leases". |
| Copies keep running after a cancel | They run until their lease ends at most (TTL, 24 h by default). Shorten the TTL if that is too long. Checks see the change within one check interval. |
| The customer did not get the paused email | Super → Email, the outbox. One email per license per 24 h. |