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#

TaskStaff roles
Change billing settings and payment providersowner, admin
View invoices, mark as paid, voidowner, admin, billing
Adjust the credit balance of an organizationowner, admin, billing
Run billing nowowner, 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.

FieldRules
CompanyRequired. Up to 120 characters.
Billing emailOptional. Must be a valid email address.
Address, Address line 2Optional. Up to 120 characters each.
Postal codeOptional. Up to 20 characters.
CityOptional. Up to 80 characters.
CountryRequired. Two-letter country code, for example NL or DE. Default: NL. Stacklane uses it to choose your VAT rate.
VAT numberOptional. Up to 20 characters.
Company registration numberOptional. Up to 40 characters.

Invoicing#

FieldDefaultRules and meaning
Invoice number prefixINV-Up to 12 letters, digits or hyphens. Numbers look like INV-2026-00001.
Payment term (days)140 to 120. The due date is the issue date plus this number of days.
CurrencyEURA three-letter currency code.
Suspend after (days overdue)140 to 365. See Reminders, suspension and restore. Use 0 to never suspend automatically.
Minimum top-up10.00The smallest amount a customer can add as credit. Between 1.00 and 10,000.00.
Charge VATOnTurn 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)OnSee 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.

MethodFieldsOffered to customers when
Bank transferIBAN, BICIt is turned on and an IBAN is set. Stacklane checks the IBAN checksum.
MollieAPI keyIt is turned on and an API key is stored.
StripeSecret keyIt is turned on and a secret key is stored.
PayPalClient ID, Client secret, Use the PayPal sandboxIt 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#

  1. The customer chooses Add credit or Pay invoice and a payment method.
  2. Stacklane creates a payment at the provider and sends the customer to the provider's checkout page.
  3. 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.
  4. 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.
  5. 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#

  1. In your Mollie dashboard, create an API key.
  2. In Billing settings, turn on Mollie and paste the key into API key.
  3. 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#

  1. In your Stripe dashboard, copy the secret key.
  2. In Billing settings, turn on Stripe and paste the key into Secret key.
  3. In the Stripe dashboard, add a webhook endpoint with the address https://panel.example.com/api/billing/v1/webhooks/stripe.
  4. 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#

  1. In the PayPal developer dashboard, create an app and copy the client ID and secret.
  2. In Billing settings, turn on PayPal and fill in Client ID and Client secret.
  3. Turn on Use the PayPal sandbox to test with sandbox accounts. Turn it off for live payments.
  4. 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 example CHECKOUT.ORDER.APPROVED and PAYMENT.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#

  1. In Billing settings, turn on Bank transfer.
  2. Fill in your IBAN and, if you want, the BIC.
  3. Click Save.

The customer sees your company name as beneficiary, the IBAN, the BIC, the amount and a reference:

Stacklane does not connect to your bank. The payment stays pending in Stacklane. When the money arrives:

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:

Every change to the balance is a line in the credit ledger. Customers see it under Billing → Transactions. The ledger uses these kinds:

KindMeaning
top_upCredit added through a payment.
invoiceCredit applied to an invoice.
chargeA domain registration paid from credit.
refundCredit returned from a voided invoice.
adjustmentA 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:

  1. records usage for the current hour;
  2. issues invoices for months that have ended;
  3. sends payment reminders;
  4. suspends or restores accounts.

What is metered#

ResourceBilled whilePrice
Cloud instanceThe instance has the status running or stopped.The monthly price of its flavor.
Extra volumeThe volume is attached to an instance that is not deleted.Size in GB times the volume price per GB per month. See Cloud.
Hosting serviceThe 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#

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:

  1. gives it the next invoice number;
  2. calculates VAT for the customer (see EU VAT rules);
  3. stores a copy of your company details and the customer's details;
  4. applies the customer's credit;
  5. sets the due date to the issue date plus the payment term;
  6. 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:

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.

SituationTreatmentRate
Charge VAT is offexempt0%
The customer has no country, or the same country as youdomesticYour country's rate
Your company country is not an EU countrydomestic0%, because Stacklane only knows EU rates
The customer is outside the EUexport0%
The customer is in another EU country and has a verified VAT numberreverse_charge0%
The customer is in another EU country without a verified VAT number, One-Stop Shop ondestinationThe customer's country rate
The customer is in another EU country without a verified VAT number, One-Stop Shop offoriginYour 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:

CountryRateCountryRateCountryRate
AT20%FI25.5%LV21%
BE21%FR20%MT18%
BG20%GR24%NL21%
CY19%HR25%PL23%
CZ21%HU27%PT23%
DE19%IE23%RO21%
DK25%IT22%SE25%
EE24%LT21%SI22%
ES21%LU17%SK23%

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 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:

  1. suspends every active hosting service of the organization on its control panel;
  2. powers off every running cloud instance;
  3. sends an email to the administrator and billing users that their services are suspended.

While an organization has such an overdue invoice, it cannot:

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"}'

The response contains the new balance:

{ "balance_cents": 2500 }

Refunds#

Stacklane does not send refunds to payment providers. To return money to a customer:

  1. Make the refund in the dashboard of the payment provider or through your bank.
  2. If the refund replaces credit, remove that credit with a negative balance adjustment.

Stacklane makes these refunds to credit by itself:

API endpoints#

MethodPathDescription
GET, PUT/api/admin/billing/settingsRead or save the billing settings.
GET/api/admin/billing/invoicesList 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}/paidMark an open invoice as paid.
POST/api/admin/billing/invoices/{id}/voidVoid an open invoice.
POST/api/admin/billing/clients/{id}/balanceAdjust the credit balance.
POST/api/admin/billing/runRun metering, invoicing, reminders and suspension now.
POST/api/billing/v1/webhooks/{provider}Webhooks for mollie, stripe and paypal.