Ошибка оплаты и возврат средств: как оформить

«Ошибка оплаты» на практике означает две разные ситуации, и путать их не стоит: либо что-то пошло не так на этапе пополнения баланса (списали, а деньги не дошли, или списали дважды), либо списание за использование API кажется неправильным (списали больше, чем ожидалось, за конкретный запрос). Возврат в этих случаях оформляется по-разному, и начинать нужно с того, чтобы понять, какой это случай.

Случай 1: деньги списаны при пополнении, а баланс не изменился

Здесь сначала стоит убедиться, что это не просто задержка обработки — платежи через СБП, карту (PayPear), крипту и иностранную карту Mastercard EU (через Fride, доступно с 16 сентября 2026 года) идут по разным маршрутам, и у каждого есть нормальное время подтверждения. Если баланс так и не пополнился спустя разумное время после подтверждения платежа банком или сетью — это уже повод оформлять возврат, а не просто ждать.

Проверить актуальный баланс можно без захода в кабинет:

curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_ваш_ключ"

Случай 2: списали дважды за одно и то же пополнение

Двойное списание при оплате картой или через СБП — это ошибка на стороне платёжного провайдера или банка-эквайера, а не что-то, что можно исправить на стороне API. Оформляется как обычный возврат: с указанием обеих транзакций, чтобы было видно, что это один и тот же платёж, прошедший дважды.

Случай 3: списание за API-запрос кажется ошибочным

Здесь важно понимать, что уже гарантировано механикой самого API:

• Если запрос не дошёл до модели (401, 402, 404, 429, 403 model_not_allowed_for_key, 503) — списания не было вообще, потому что баланс проверяется до обращения к провайдеру. Возвращать тут нечего, потому что и списывать было нечего.
• Если ответ оборвался на середине — это почти всегда таймаут клиента или сети, а не превышение лимита по токенам. Обрыв не останавливает списание: шлюз дочитывает ответ провайдера и списывает всю генерацию, поэтому такое списание корректно.
• Повторный одинаковый запрос с одним и тем же Idempotency-Key в течение 24 часов не может списать дважды по определению — вернётся тот же ответ без повторного списания.

Прежде чем писать в поддержку про «лишнее» списание, стоит сверить фактическую стоимость запроса. У каждого обычного (нестримингового) ответа есть заголовок X-Zukko-Cost-Micros — точная стоимость именно этого запроса в микродолларах (1 000 000 = $1); у потоковых ответов (stream: true) этого заголовка нет. Всю историю списаний можно поднять через GET /v1/usage — она общая на аккаунт (все ключи вместе, фильтра по ключу нет), у каждой записи есть created_at, model, input_tokens, output_tokens, total_tokens и cost_cents:

curl https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_ваш_ключ"

Если после сверки видно, что за один и тот же запрос списание произошло дважды — то есть в истории две одинаковые по времени и содержанию записи без соответствующих двух реальных запросов с вашей стороны — вот это уже техническая ошибка, а не нормальное поведение биллинга, и повод писать в поддержку.

Что не является поводом для возврата

• Кэшированный ответ (X-Zukko-Cache: hit, срабатывает при заголовке X-Zukko-Cache: true или temperature: 0 у моделей, которые принимают этот параметр, и только при полном совпадении тела запроса) не списывается вообще и не попадает в /v1/usage — если в истории есть списание за такой запрос, значит, ответ пришёл не из кэша.
• Выключенная модель отвечает ошибкой 503 model_disabled и не выполняется — списания за такой запрос быть не может.
• Собственная опечатка в имени модели (model_not_found) — это не повод для возврата, запрос до модели просто не дошёл и не был оплачен.

Если это повторяется не в первый раз

Если один и тот же способ оплаты уже давал сбой с двойным списанием раньше, стоит упомянуть это в новом обращении. Это ускоряет разбор: поддержка смотрит не на единичный случай, а на историю по конкретному способу оплаты, и при необходимости эскалирует проблему на сторону провайдера, а не просто возвращает сумму по одной транзакции.

Как оформить обращение

Пишите в поддержку: https://t.me/zukkopro?direct↗. Чтобы не тратить несколько раундов переписки на уточнения, сразу приложите:

• что произошло: не дошло пополнение, двойное списание за пополнение, или спорное списание за API-запрос;
• для пополнения — способ оплаты, сумму, время, скриншот из банка или хэш транзакции для крипты;
• для спорного списания за API — примерное время запроса, использованную модель, и, если есть, значение X-Zukko-Cost-Micros из ответа или соответствующую запись из GET /v1/usage;
• email или идентификатор аккаунта.

Чего ждать дальше

Возврат при ошибке платёжного провайдера (двойное списание, недошедший платёж) зависит от скорости самого провайдера — СБП, PayPear, крипто-сети или Fride — и это не всегда мгновенно, потому что деньги физически нужно провести через ту же цепочку, через которую они списывались. Технический спор по списанию за API-запрос решается быстрее, поскольку вся нужная информация — в логах /v1/usage и в заголовках ответов, которые можно свести и проверить без внешних платёжных систем.