# 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.

## Invoices and history

Each completed purchase produces an invoice, visible under **Billing** in the
dashboard along with the full balance history. Its single line item 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.

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.

Workspaces on invoiced
(postpaid) billing — available by arrangement — skip the upfront balance
requirement and receive a monthly invoice for what accrued instead.