---
search:
  tags:
    - billing
    - POST
seo:
  description: >-
    Starts a payment for amount_eur of credit (at list prices, which include
    17%… Reference for the POST /v1/billing/topups endpoint in the pols.so API.
sidebar:
  label: Start a top-up of the org's prepaid credit, paid on Mollie's checkout
  badge: POST
title: Start a top-up of the org's prepaid credit, paid on Mollie's checkout
type: openapi-operation
---
Starts a payment for `amount_eur` of credit (at list prices, which
include 17% Luxembourg VAT; EUR 5 to EUR 1,000 in whole cents) at
Mollie, the payment provider, and returns it with `checkout_url`,
the page on mollie.com where it is paid. What it charges
(`charged_eur`) follows `tax_treatment`, from the org's billing
details as they are now: `lu_vat` charges the amount, VAT
included; `reverse_charge` and `outside_eu` charge it less the
VAT (`amount_eur` / 1.17, rounded to the cent). Once Mollie
confirms the payment, the org gets prepaid credit of `amount_eur`,
which never expires (`/v1/balance`), once, and the top-up gets
its invoice (`invoice_id`). A failed, canceled or expired payment
grants nothing. Owners' and admins' keys only (403 `forbidden`
otherwise).

The org must have saved its billing details (`/v1/billing`) first
(409 `billing_details_required`). 409 `topup_not_available`, with
a message saying why: the org cannot top up as it would be taxed,
for now a consumer outside the EU (a business there needs its tax
ID in its billing details), or a consumer in another EU country
once the year's such sales reached the EU threshold. An amount out
of bounds is 400 `bad_request`; more than 10 top-ups started in an
hour is 429 `rate_limited`. 502 `payment_provider_error`: Mollie
could not be reached or refused the payment; nothing is charged.
503 `unavailable`: the deployment takes no payments. While `test`
is true, payments go through Mollie's test mode and no money
moves, and their invoices are drafts.

`POST /v1/billing/topups`