# Payments & the wallet All prices are **EUR**, quoted retail, per year, and **VAT-inclusive** — the number you are quoted is the number you pay. The quote you act on comes from `GET /api/v1/check` (registration) or `GET /api/v1/tlds` (register / renew / transfer per TLD). ## The wallet Every workspace has a wallet; every purchase debits it. Fund it either way: **Top up** — dashboard → **Billing → Top up** (Stripe Checkout). The balance is credited when the payment completes. **Pay as you go** — pass a payment instrument on the spending call itself: ```json { "domain": "example.com", "duration": 1, "confirm_price": 18, "payment_method": "pm_…" } ``` The exact price is charged, credited to the wallet, and debited by the purchase — net card movement equals the price, no standing balance needed. `shared_payment_token` is accepted in place of `payment_method` for agent frameworks that issue Stripe shared payment tokens. ## `confirm_price` Spending verbs (`POST /domains`, `POST /domains/{name}/renew`, `POST /domains/{name}/transfer`) require `confirm_price` — the total you were quoted (unit price × duration for multi-year operations). The server re-resolves the live price and compares within €0.01: - Match → the operation proceeds and the wallet is debited on success. - Mismatch → `409 price_changed` with both prices in `details`; nothing is charged. Re-quote and retry with the current price if it's acceptable: ```json { "error": "price_changed", "details": { "message": "The price has changed. Re-check before purchasing.", "confirmed_price": 18, "current_price": 21, "currency": "EUR" } } ``` ## Failure semantics — why there are no refunds to wait for The order of operations is: charge (if pay-as-you-go) → credit wallet → verify balance → **registry action** → debit wallet. If the registry action fails, the debit never happens: the money stays as wallet credit and the retry uses it without touching your card again. You are never waiting on a refund to retry. If the wallet can't cover the price and no payment instrument was passed, you get `402 insufficient_balance` with `required` and `available` amounts in cents — top up or attach a payment method and retry. ## Auto-renew Auto-renew is on by default and is billed from the wallet like any other purchase, just without a `confirm_price` — the setting is the consent, at the renewal price listed in `GET /api/v1/tlds`. - About **30 days before expiry** the domain is renewed for a year and the wallet is debited; the invoice covers the year appended to the current expiry. - If the wallet can't cover it, the renewal is retried daily. Still unpaid **10 days before expiry**, it is dropped and the domain is left to expire — top up and renew by hand (`POST /domains/{name}/renew`) to keep it. - Turning auto-renew **off before the charge** (`PATCH /domains/{name}/settings` with `auto_renew: false`) costs nothing. **After the charge** the renewal stands and is not refunded; turning it off stops the following year, and the response carries `renewed_until`. - Turning it **on inside those last 30 days** renews right away. A renew call for a term that is already being bought answers `409 renewal_in_progress`. ### Seeing what's coming `GET /api/v1/domains/{name}` carries a `renewal` object — the same one the MCP `get_domain` tool and `domains settings ` render: ```json { "renewal": { "auto_renew": true, "expires_at": "2026-10-31", "billed_until": "2026-10-31", "next_charge_at": "2026-10-01", "price": 18, "currency": "EUR", "follows_registry": false, "charge_lead_days": 30, "phase": "idle", "term": null } } ``` - `next_charge_at` is the day the wallet is charged, `price` what it costs. - `billed_until` is what you have already paid for — past the expiry while a paid renewal is still being processed at the registry. - `term` appears once the renewal has been attempted. `state: "awaiting_funds"` with `reason: "insufficient_balance"` carries `shortfall` — the EUR to top up; the charge is retried daily until 10 days before expiry. `state: "lapsed"` means it was dropped: renew by hand. `state: "refunded"` means we charged you but the registry did not perform the renewal: the full amount is back on your balance and the domain is not renewed, so renew it by hand if you still want it. - `follows_registry: true` (workspaces billed by arrangement) means nothing is charged ahead of the registry — it renews and you are billed afterwards, so there is no `next_charge_at`. ## Invoices and history Every purchase ends up on an invoice, visible under **Billing** in the dashboard along with the full balance history. Each line names the operation and the domain (`Registration: example.com (2y)`) and carries the service period that operation bought — for a renewal, the term appended to the existing expiry, not the date you paid. By default each purchase gets its own invoice, issued as soon as it completes. Workspaces can instead be invoiced **daily, weekly or monthly**, in which case every purchase in the period is drawn onto one invoice shortly after the period ends. Either way the lines are the same; only the document they arrive on differs. Ask us to change the period for your workspace. Topping up is not itself a purchase, so it produces a Stripe **payment receipt** rather than an invoice: at that moment nothing has been supplied yet. The per-purchase invoices are the tax documents, and prices are VAT-inclusive — the figure you confirm through `confirm_price` is the figure debited and the figure on the invoice, with any VAT broken out inside it. **Business customers:** set your workspace's default contact to an *organization* contact and fill in its VAT number. That number goes onto your invoices, and for EU businesses outside our country it applies **reverse charge** (0% VAT). An individual default contact is invoiced as a consumer. ## Paying on credit By arrangement, a workspace can be put **on credit** instead of prepaid: there is no balance to keep topped up, purchases go straight through, and the invoice for them is a real open invoice you pay like any other — that payment is how the money reaches us, so nothing is deducted from a balance. Spending is bounded by an agreed credit limit; a purchase that would cross it is refused with `402 insufficient_balance`, carrying the remaining credit in `available`. Settle an open invoice, or ask us to raise the limit.