Payment errors and refunds: how to file one

"Payment error" covers two different situations in practice, and it is worth telling them apart before writing to anyone: either something went wrong at the top-up stage — money got charged but never reached the balance, or it got charged twice — or a charge for actual API usage looks wrong. Refunds are filed differently in each case, so start by figuring out which one you have.

Case 1: money was charged on top-up, but the balance did not change

First rule out a simple processing delay — payments via SBP, card (PayPear), crypto, and foreign Mastercard EU cards (via Fride, available since September 16, 2026) all travel different routes, each with its own normal confirmation time. If the balance still has not moved a reasonable while after the bank or network confirmed the payment, that is worth filing a refund request over rather than continuing to wait.

Check the current balance without opening the dashboard:

curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_your_key"

Case 2: charged twice for the same top-up

A double charge on a card or SBP payment is an error on the payment provider's or acquiring bank's side, not something the API itself can fix. File it as a standard refund request, pointing at both transactions so it is clear they are the same payment processed twice.

Case 3: an API charge looks wrong

It helps to know what the API's own mechanics already guarantee here:

• If a request never reached the model (401, 402, 404, 429, 403 model_not_allowed_for_key, 503), nothing was charged at all, because the balance is checked before the provider is contacted. There is nothing to refund because there was nothing charged.
• If a response cut off midway, that is almost always a client or network timeout, not a token-limit issue. A cut-off does not stop billing: the gateway reads the provider's response to the end and charges for the full generation, so the charge is correct.
• A repeated identical request with the same Idempotency-Key within 24 hours cannot be charged twice by design — it returns the same response without a second charge.

Before writing to support about a charge that seems off, cross-check the actual cost of the request. Every regular (non-streaming) response carries an X-Zukko-Cost-Micros header — the exact cost of that specific request in micro-dollars (1,000,000 = $1); streaming responses (stream: true) do not include it. You can pull the full billing history via GET /v1/usage — it covers the whole account (all keys together, no per-key filter), and each entry has created_at, model, input_tokens, output_tokens, total_tokens, and cost_cents:

curl https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_your_key"

If, after cross-checking, you see the same request charged twice — two identical entries in the history matching in time and content, without two matching real requests on your side — that is an actual technical error, not normal billing behavior, and worth writing to support about.

What is not grounds for a refund

• A cached response (X-Zukko-Cache: hit, triggered by the X-Zukko-Cache: true header, or by temperature: 0 on models that accept that parameter, and only on an exact match of the request body) is not charged at all and does not appear in /v1/usage — if the history shows a charge for a request, that response did not come from cache.
• A disabled model returns a 503 model_disabled error and never executes — there is no way it was charged.
• Your own typo in a model name (model_not_found) is not grounds for a refund — the request never reached a model and was never billed.

How to file it

Contact support at https://t.me/zukkopro?direct↗. To avoid several rounds of back-and-forth, attach right away:

• what happened: a top-up that never arrived, a double charge on a top-up, or a disputed API charge;
• for a top-up issue — payment method, amount, time, a bank screenshot, or a transaction hash for crypto;
• for a disputed API charge — the approximate time of the request, the model used, and, if you have it, the X-Zukko-Cost-Micros value from the response or the matching entry from GET /v1/usage;
• your email or account identifier.

What to expect next

A refund for a payment-provider error (double charge, a payment that never arrived) depends on how fast that specific provider — SBP, PayPear, a crypto network, or Fride — moves, and that is not always instant, since the money has to physically travel back through the same chain it was charged through. A technical dispute over an API charge tends to resolve faster, since everything needed is already in the /v1/usage logs and response headers, and can be checked without involving outside payment systems.