Start a top-up of the org's prepaid credit, paid on Mollie's checkout

Starts a payment for amount_eur of credit (at list prices, which exclude 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, which is net_eur plus vat_eur) follows tax_treatment, from the org’s billing details as they are now: lu_vat adds 17% Luxembourg VAT to the amount (rounded half up to the cent), so EUR 5.00 of credit charges EUR 5.85; reverse_charge and outside_eu charge the amount, without VAT. 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.

A consumer, or a business whose VAT ID VIES has not confirmed, has a right of withdrawal for 14 days (https://pols.so/withdrawal/) and orders only with withdrawal_consent: “I expressly request that pols.so start providing the service now, before the 14-day withdrawal period ends, so that I can use the credit straight away. I understand that if I withdraw, I pay for the credit I have used until then, and that I lose my right of withdrawal once all of this credit has been used.” Without it, 409 withdrawal_consent_required. The consent is recorded with the top-up: when, its wording and the caller’s address. The order is confirmed by email once paid, with the terms of service (https://pols.so/terms/) attached; in German when Accept-Language prefers it.

POST/v1/billing/topups

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Request body

requiredapplication/json

amount_eurstringrequired

Euros of credit at list prices, VAT excluded, from 5 to 1000 in whole cents; VAT is added as tax_treatment says.

withdrawal_consentboolean

The buyer expressly requests that pols.so start now, before the 14-day withdrawal period ends, and acknowledges that if they withdraw they pay for the credit used until then, and lose the right once all of it is used (createTopUp has the wording). Required for a consumer, or a business whose VAT ID VIES has not confirmed.

Responses

201

The top-up, open for payment at checkout_url.

idstringrequired

amount_eurstringrequired

The credit it adds, at list prices, which exclude VAT; decimal string with 2 places.

net_eurstringrequired

What it charges before VAT: amount_eur. For a top-up from before net prices, whose amount included VAT, the amount less that VAT. A top-up from before invoices (tax_treatment null) has no record of its VAT: its net and VAT are not known, and this is charged_eur.

vat_eurstringrequired

The VAT it charges, "0.00" without VAT (tax_treatment). For a top-up from before invoices (tax_treatment null), whose VAT is not known, "0.00".

charged_eurstringrequired

What Mollie charges, net_eur plus vat_eur.

tax_treatmentTaxTreatment | nullrequired

How VAT applies to it, fixed when it started; null for a top-up from before invoices.

Show properties

Any of:

TaxTreatment

string

null

null

statusTopUpStatusrequired

Where the top-up's payment stands at Mollie. open: waiting to be paid at checkout_url. pending: started, waiting for the bank or card issuer. authorized: authorized, not yet captured. paid: paid; the credit was added. canceled, expired, failed: not paid, and nothing was added. The last four are final.

Allowed:openpendingauthorizedpaidcanceledexpiredfailed

testbooleanrequired

Paid in Mollie's test mode, which moves no money.

checkout_urlstring | nullrequired

Where the top-up is paid, on mollie.com, while it is open; null otherwise.

credit_lot_idstring | nullrequired

The prepaid credit lot the paid top-up added (/v1/balance); null until it is paid.

invoice_idstring | nullrequired

The paid top-up's invoice (/v1/invoices/{invoice}); null until it is issued, and for a top-up from before invoices.

created_atstring<date-time>required

paid_atstring<date-time> | nullrequired

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request

curl -X POST 'https://api.pols.so/v1/billing/topups' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_eur": "25.00",
  "withdrawal_consent": true
}'

const response = await fetch("https://api.pols.so/v1/billing/topups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"amount_eur\": \"25.00\",\n  \"withdrawal_consent\": true\n}"
});

import requests

response = requests.post(
    "https://api.pols.so/v1/billing/topups",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"amount_eur\": \"25.00\",\n  \"withdrawal_consent\": true\n}",
)

Response

{
  "id": "pay_3k9x2m1q8zt4",
  "amount_eur": "25.00",
  "net_eur": "25.00",
  "vat_eur": "4.25",
  "charged_eur": "29.25",
  "tax_treatment": "lu_vat",
  "status": "open",
  "test": true,
  "checkout_url": "string",
  "credit_lot_id": "string",
  "invoice_id": "inv_8f2k4m9q1x7c",
  "created_at": "2019-08-24T14:15:22Z",
  "paid_at": "2019-08-24T14:15:22Z"
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}