Billing
Stacklane measures usage every hour, sends one invoice per organization every month and collects payments through Mollie, Stripe, PayPal or bank transfer. Customers can also pay in advance with credit. This page explains each part and the settings that control it.
Who can do what#
| Task | Staff roles |
|---|---|
| Change billing settings and payment providers | owner, admin |
| View invoices, mark as paid, void | owner, admin, billing |
| Adjust the credit balance of an organization | owner, admin, billing |
| Run billing now | owner, admin |
Billing settings#
Open Billing settings in the Billing group of the back office. Fill in the form and click Save.
Company details#
These details are shown as the seller on every invoice. Stacklane copies them into each invoice when it is issued, so later changes do not change old invoices.
| Field | Rules |
|---|---|
| Company | Required. Up to 120 characters. |
| Billing email | Optional. Must be a valid email address. |
| Address, Address line 2 | Optional. Up to 120 characters each. |
| Postal code | Optional. Up to 20 characters. |
| City | Optional. Up to 80 characters. |
| Country | Required. Two-letter country code, for example NL or DE. Default: NL. Stacklane uses it to choose your VAT rate. |
| VAT number | Optional. Up to 20 characters. |
| Company registration number | Optional. Up to 40 characters. |
Invoicing#
| Field | Default | Rules and meaning |
|---|---|---|
| Invoice number prefix | INV- | Up to 12 letters, digits or hyphens. Numbers look like INV-2026-00001. |
| Payment term (days) | 14 | 0 to 120. The due date is the issue date plus this number of days. |
| Currency | EUR | A three-letter currency code. |
| Suspend after (days overdue) | 14 | 0 to 365. See Reminders, suspension and restore. Use 0 to never suspend automatically. |
| Minimum top-up | 10.00 | The smallest amount a customer can add as credit. Between 1.00 and 10,000.00. |
| Charge VAT | On | Turn this off if you do not charge VAT at all. All invoices then have a VAT rate of 0%. |
| Use the destination rate for EU consumers (One-Stop Shop) | On | See EU VAT rules. |
Currency. Every price in Stacklane must use the billing currency. When you save a flavor, a hosting plan or an extension price in another currency, Stacklane rejects it. Set the currency before you create prices.
Invoice numbers. The number is the prefix, the year, a hyphen and a sequence number of five digits. The sequence starts again at 1 every calendar year.
Payment methods#
Each method has a checkbox to turn it on. Secret keys are stored encrypted with the secret key of the server and are never shown again. To keep the current key, leave the field empty when you save. A badge shows Configured when a key is stored.
| Method | Fields | Offered to customers when |
|---|---|---|
| Bank transfer | IBAN, BIC | It is turned on and an IBAN is set. Stacklane checks the IBAN checksum. |
| Mollie | API key | It is turned on and an API key is stored. |
| Stripe | Secret key | It is turned on and a secret key is stored. |
| PayPal | Client ID, Client secret, Use the PayPal sandbox | It is turned on and both a client ID and a client secret are stored. |
Customers see the methods with these names: "iDEAL, Bancontact, card and more" (Mollie), "Credit or debit card" (Stripe), "PayPal" and "Bank transfer".
The settings page shows the webhook address for your providers:
https://panel.example.com/api/billing/v1/webhooks/<mollie|stripe|paypal>
The address uses server.public_url from the configuration file.
Payment providers#
How online payments work#
- The customer chooses Add credit or Pay invoice and a payment method.
- Stacklane creates a payment at the provider and sends the customer to the provider's checkout page.
- After payment, the provider sends the customer back to
https://panel.example.com/billing/payments/<id>. That page shows the result and updates itself while the payment is still open. - Stacklane asks the provider for the status of the payment. It does this when a webhook arrives and when the customer views the payment page.
- When the provider reports the payment as paid:
- a payment for an invoice marks the invoice as paid;
- a top-up adds the amount to the customer's credit balance.
If an invoice was already paid in another way, or is no longer open, the money is added to the credit balance instead.
Stacklane never trusts the content of a webhook. It only reads the payment reference from the webhook, finds the matching payment and asks the provider for the real status. Webhooks for unknown payments are answered with 200 and ignored.
Mollie#
- In your Mollie dashboard, create an API key.
- In Billing settings, turn on Mollie and paste the key into API key.
- Click Save.
You do not need to set a webhook in the Mollie dashboard. Stacklane sends the webhook address /api/billing/v1/webhooks/mollie with every payment it creates.
Stripe#
- In your Stripe dashboard, copy the secret key.
- In Billing settings, turn on Stripe and paste the key into Secret key.
- In the Stripe dashboard, add a webhook endpoint with the address
https://panel.example.com/api/billing/v1/webhooks/stripe. - Send Checkout Session events to it, for example
checkout.session.completed.
Stacklane creates Stripe Checkout Sessions. It reads data.object.id from the webhook event, which must be the ID of the Checkout Session.
PayPal#
- In the PayPal developer dashboard, create an app and copy the client ID and secret.
- In Billing settings, turn on PayPal and fill in Client ID and Client secret.
- Turn on Use the PayPal sandbox to test with sandbox accounts. Turn it off for live payments.
- In the PayPal app, add a webhook with the address
https://panel.example.com/api/billing/v1/webhooks/paypal. Send it events about orders and captures, for exampleCHECKOUT.ORDER.APPROVEDandPAYMENT.CAPTURE.COMPLETED.
Stacklane creates PayPal orders with the intent CAPTURE. When it sees that an order is approved, it captures the payment. From the webhook it reads resource.supplementary_data.related_ids.order_id, or resource.id when that is missing.
Bank transfer#
- In Billing settings, turn on Bank transfer.
- Fill in your IBAN and, if you want, the BIC.
- Click Save.
The customer sees your company name as beneficiary, the IBAN, the BIC, the amount and a reference:
- for an invoice, the reference is the invoice number;
- for a top-up, the reference is
TOPUP-followed by ten characters.
Stacklane does not connect to your bank. The payment stays pending in Stacklane. When the money arrives:
- for an invoice, open the invoice in Invoices and click Mark as paid;
- for a top-up, add the amount to the customer's credit with a balance adjustment.
Test without a provider#
With billing.simulate = true in the configuration file, Stacklane approves payments without contacting a provider. Use this only for evaluation and development. See Configuration.
Credit#
Every organization has a credit balance. The customer adds credit with Add credit on the billing page. The amount must be at least the minimum top-up and at most 100,000.00.
Stacklane uses credit in these ways:
- Invoices. When Stacklane issues an invoice, it uses the available credit first. If the credit covers the total, the invoice is paid at once.
- Domains. Domain registrations and renewals are paid from credit directly. See Domains and DNS.
Every change to the balance is a line in the credit ledger. Customers see it under Billing → Transactions. The ledger uses these kinds:
| Kind | Meaning |
|---|---|
top_up | Credit added through a payment. |
invoice | Credit applied to an invoice. |
charge | A domain registration paid from credit. |
refund | Credit returned from a voided invoice. |
adjustment | A manual change by staff, or an automatic refund for a failed domain registration or renewal. |
Metering#
A background job runs every five minutes. Each run:
- records usage for the current hour;
- issues invoices for months that have ended;
- sends payment reminders;
- suspends or restores accounts.
What is metered#
| Resource | Billed while | Price |
|---|---|---|
| Cloud instance | The instance has the status running or stopped. | The monthly price of its flavor. |
| Extra volume | The volume is attached to an instance that is not deleted. | Size in GB times the volume price per GB per month. See Cloud. |
| Hosting service | The service is active or suspended. | The monthly price of its plan. |
A stopped instance is still billed. Instances that are being created, have an error or are deleted are not billed.
How a month is calculated#
- Stacklane counts whole hours. A resource that exists at any run during a clock hour is counted for that hour. Each hour is counted only once.
- A month has 730 hours for billing. The charge for a month is: hours used × monthly price ÷ 730, rounded to the nearest cent.
- The charge never goes above the monthly price. After 730 hours, more hours in the same month are free.
- Months are calendar months in UTC.
- The usage line stores the latest monthly price. If you change a price during a month, the whole month of a running resource is invoiced at the new price.
Customers see the usage of the current month, with an estimate including VAT, on their billing page.
Invoices#
Monthly invoicing#
At the first run after a month ends, Stacklane issues one invoice per organization for all usage of that month. Each line shows the resource, the number of hours, the monthly price and the amount.
When Stacklane issues an invoice, it:
- gives it the next invoice number;
- calculates VAT for the customer (see EU VAT rules);
- stores a copy of your company details and the customer's details;
- applies the customer's credit;
- sets the due date to the issue date plus the payment term;
- sends an email to every active user of the organization with the administrator or billing role.
An invoice has one of these statuses: open, paid or void. The portal also shows Overdue for an open invoice after its due date.
Manage invoices#
Open Invoices in the Billing group. You see the invoices of all organizations. Filter by status, and click an invoice to see the details.
On an open invoice you can:
- Mark as paid. Use this after you receive a bank transfer or another payment outside Stacklane. The amount due becomes 0.
- Void invoice. Use this to correct an invoice. Stacklane returns the credit that was applied to the invoice to the customer. The usage on the invoice becomes uninvoiced again, so the next run issues a new invoice for the same usage, normally within five minutes.
Paid and void invoices cannot be changed.
Customers can print each invoice or save it as a PDF with Download PDF. An invoice with reverse charge or export shows a VAT notice.
Run billing now#
Staff with the owner or admin role can click Run billing now on the Invoices page. Stacklane then runs all four steps of the background job at once, and shows how many invoices it issued. This is useful after you void an invoice or change settings.
EU VAT rules#
Stacklane decides the VAT rate and treatment for each customer when it issues an invoice. It uses your company country, the Charge VAT and One-Stop Shop settings, and the customer's country and verified VAT number.
| Situation | Treatment | Rate |
|---|---|---|
| Charge VAT is off | exempt | 0% |
| The customer has no country, or the same country as you | domestic | Your country's rate |
| Your company country is not an EU country | domestic | 0%, because Stacklane only knows EU rates |
| The customer is outside the EU | export | 0% |
| The customer is in another EU country and has a verified VAT number | reverse_charge | 0% |
| The customer is in another EU country without a verified VAT number, One-Stop Shop on | destination | The customer's country rate |
| The customer is in another EU country without a verified VAT number, One-Stop Shop off | origin | Your country's rate |
The same rules are used for the price estimates that customers see before they create an instance.
Standard rates#
Stacklane uses these standard rates:
| Country | Rate | Country | Rate | Country | Rate |
|---|---|---|---|---|---|
| AT | 20% | FI | 25.5% | LV | 21% |
| BE | 21% | FR | 20% | MT | 18% |
| BG | 20% | GR | 24% | NL | 21% |
| CY | 19% | HR | 25% | PL | 23% |
| CZ | 21% | HU | 27% | PT | 23% |
| DE | 19% | IE | 23% | RO | 21% |
| DK | 25% | IT | 22% | SE | 25% |
| EE | 24% | LT | 21% | SI | 22% |
| ES | 21% | LU | 17% | SK | 23% |
VIES checks#
A customer enters the VAT number and country under Settings → General information. When the customer saves, Stacklane checks the number in the VIES service of the European Commission.
- The number must start with the country prefix. For Greece the prefix is
EL. Spaces and dots are removed. - If VIES confirms the number, it is verified. Reverse charge then applies to invoices across EU borders.
- If VIES rejects the number, it stays not verified, and VAT is charged.
- If VIES is not available, the number stays not verified. Stacklane checks again the next time the customer saves the details.
- When the customer changes the VAT number or the country, the number must be verified again.
The customer sees the result next to the VAT number field.
Reminders, suspension and restore#
Reminder#
When an open invoice passes its due date and still has an amount due, Stacklane sends one reminder email to the users with the administrator or billing role. It sends only one reminder per invoice.
Suspension#
When an open invoice is more days past its due date than the Suspend after setting, Stacklane:
- suspends every active hosting service of the organization on its control panel;
- powers off every running cloud instance;
- sends an email to the administrator and billing users that their services are suspended.
While an organization has such an overdue invoice, it cannot:
- create instances, or start or reboot them;
- add volumes;
- order hosting;
- register domains.
These requests return 402 with the error code billing_hold. Other actions, such as paying the invoice, still work.
With Suspend after set to 0, Stacklane never suspends accounts and never returns billing_hold.
Restore#
When the organization has no overdue invoice anymore, the next run restores the hosting services that Stacklane suspended for billing. An invoice stops being overdue when it is paid, marked as paid or voided.
Cloud instances are not started again. The customer starts them in the portal, which is allowed again once the invoice is settled.
Adjust a credit balance#
You can add or remove credit for an organization through the API. There is no screen for it in the portal. You need the owner, admin or billing staff role.
Back-office endpoints only accept the access token of a signed-in staff member, not an API token. See API for how to get one.
curl -X POST https://panel.example.com/api/admin/billing/clients/42/balance \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"amount_cents": 2500, "description": "Bank transfer TOPUP-9F2C41D07A"}'
42is the ID of the organization. The customer sees it as Account ID on the dashboard.amount_centsis positive to add credit and negative to remove credit. It cannot be 0, and the maximum is 1,000,000.00 in either direction.descriptionis required, up to 200 characters. The customer sees it in the ledger.
The response contains the new balance:
{ "balance_cents": 2500 }
Refunds#
Stacklane does not send refunds to payment providers. To return money to a customer:
- Make the refund in the dashboard of the payment provider or through your bank.
- If the refund replaces credit, remove that credit with a negative balance adjustment.
Stacklane makes these refunds to credit by itself:
- when you void an invoice that used credit;
- when a domain registration or renewal fails after the customer paid for it.
API endpoints#
| Method | Path | Description |
|---|---|---|
GET, PUT | /api/admin/billing/settings | Read or save the billing settings. |
GET | /api/admin/billing/invoices | List invoices. Query: status (open, paid, void), client_id, limit, offset. |
GET | /api/admin/billing/invoices/{id} | Invoice with lines, customer and seller details. |
POST | /api/admin/billing/invoices/{id}/paid | Mark an open invoice as paid. |
POST | /api/admin/billing/invoices/{id}/void | Void an open invoice. |
POST | /api/admin/billing/clients/{id}/balance | Adjust the credit balance. |
POST | /api/admin/billing/run | Run metering, invoicing, reminders and suspension now. |
POST | /api/billing/v1/webhooks/{provider} | Webhooks for mollie, stripe and paypal. |