Когда покупка в Google Play возвращается или оспаривается, узнать об этом можно через Voided Purchases API

Возврат в Google Play не стучится к вам в дверь. Деньги уходят, клиент продолжает держать приложение открытым, и, пока вы не пойдёте искать, с вашей стороны ничего не меняется. Voided Purchases API и есть то место, куда вы идёте искать. Он выдаёт вам список заказов, которые были отменены, возвращены или оспорены, чтобы вы могли отозвать доступ к тому, за что клиент больше не платит. Направьте на него запланированную задачу, прочитайте список, обрежьте право доступа. Вот и весь цикл.

Есть одна загвоздка, на которой спотыкается большинство команд, и она не в коде. Здесь появляются только заказы, которые были отозваны. Если вы вернёте покупку в Play Console, не отметив опцию отзыва, этот заказ никогда не попадёт в этот API, и ваша задача отработает вчистую, пока клиент с возвратом сохраняет всё, что вы ему продали. Эта статья проходит по API поле за полем, по числам, которые его ограничивают, и по тому, где утекают деньги, когда вы им пренебрегаете.

Что на самом деле возвращает Voided Purchases API

API отвечает на один вопрос: какие заказы этого приложения были аннулированы недавно. Аннулирование охватывает три исхода, каждый из которых заканчивается тем, что клиент получает деньги обратно. Отмена, возврат или чарджбэк. Оно применяется к разовым внутренним продуктам приложения и к подпискам, а объём вы выбираете одним параметром. Установите type в 0, и вы получите только аннулированные покупки разовых продуктов, это значение по умолчанию. Установите его в 1, и вы получите аннулированные разовые покупки и аннулированные покупки подписок вместе.

Каждая запись в списке представляет собой объект аннулированной покупки. Полей немного, и каждое из них имеет значение.

Поля аннулированной покупки

Прочитайте voidedReason, прежде чем действовать

Именно voidedReason превращает сырой список в решение. Возврат из-за передумавшего покупателя и банковский чарджбэк попадают в один и тот же список, но это не одно и то же событие, и августовские расценки делают одно из них дорогим. Вот полный набор.

Окно в 30 дней: ловушка, которая опустошает ваш список

Voided Purchases API может показать только аннулированные покупки за последние 30 дней. Параметр startTime по умолчанию равен текущему времени минус 30 дней, и его нельзя установить старше этого. endTime по умолчанию равен текущему моменту. Так что эндпойнт представляет собой скользящее окно в один месяц, а не архив.

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

Опция отзыва решает, появится ли заказ вообще

Это самая частая причина, по которой команда сообщает, что API сломан. Возвращаются только отозванные заказы. Возвраты, инициированные пользователем, отмены, чарджбэки и возвраты, инициированные Google, всегда отзываются, поэтому всегда появляются. Возврат, инициированный разработчиком, отличается. Когда вы возвращаете заказ сами, через Play Console или Orders API, вы выбираете, отзывать ли его также. Верните без отзыва, и заказ будет улажен с клиентом, но никогда не всплывёт в Voided Purchases API.

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

Как опрашивать его, не превышая квоту

У эндпойнта есть ограничение частоты, и лимиты достаточно низкие, чтобы наивный цикл их достиг. Вам доступно 6000 запросов в день, отсчитываемых по тихоокеанскому времени, и не более 30 запросов в любой 30-секундный период. Этого бюджета достаточно для оконного опроса, и он враждебен схемам с одним запросом на заказ.

Окна запросов и токен продолжения

maxResults по умолчанию равен 1000, что также является потолком. Когда окно содержит больше одной страницы аннулирований, ответ несёт объект tokenPagination с nextPageToken. Передайте этот токен обратно в следующем вызове, чтобы пройти по страницам. Установите startTime и endTime, чтобы ограничить нужное вам окно, листайте страницы, пока токен не закончится, затем сдвиньте окно. Эта схема удерживает вас внутри как лимита всплеска в 30 секунд, так и суточного потолка.

Real-time developer notifications закрывают разрыв

Опрос каждый день всё равно оставляет до суток слепоты, а окно в 30 дней наказывает за долгие перерывы. Real-time developer notifications убирают задержку. Google публикует VoidedPurchaseNotification в топик Cloud Pub/Sub, которым вы владеете, в тот момент, когда покупка аннулируется, и ваш бэкенд обрабатывает её за секунды. Сообщение небольшое.

Во что это обходится вам в деньгах

API является всего лишь инфраструктурой, но подключают его ради счёта. Каждое аннулирование в том списке соответствует реальной сумме, и две из них становятся дороже.

Счёт за чарджбэк ложится на вас с 3 августа 2026 года

Начиная с 3 августа 2026 года Google перекладывает стоимость чарджбэка на разработчика. Вы теряете цену покупки и вдобавок платите банковскую комиссию за чарджбэк. voidedReason, равный 7, больше не просто потерянная продажа, это строка расходов с прикреплённой комиссией. Отменить чарджбэк нельзя, он окончателен на стороне банка, но вы можете остановить кровотечение после него. Быстрый перехват аннулирования позволяет отозвать право доступа и, для всего, что вы ещё поставляете, перестать тратиться на клиента, которому вернули деньги, а затем откатили платёж.

Вы продолжаете платить за обслуживание клиента с возвратом

Цена покупки потеряна в тот момент, когда появляется аннулирование. То, что вы всё ещё контролируете, это стоимость продолжения поставки. Каждый час, пока возвращённое право доступа остаётся активным, вы продолжаете платить за то, что клиент больше не финансирует: вычисления, вызовы API моделей, хранилище и любые выплаты авторам или партнёрам, привязанные к его использованию. Система отзыва, управляемая этим API, это то, чем вы выключаете этот счётчик. Пропустите её, и вы финансируете продукт для людей, с которыми магазин уже рассчитался.

Дружественное мошенничество: паттерн, который стоит отслеживать

voidedReason, равный 5 или 6, не единичный случай. Мошенничество и дружественное мошенничество группируются по аккаунту, по устройству, а иногда по акции. API даёт вам voidedSource и voidedReason по каждому аннулированию, и этого достаточно, чтобы отслеживать злоупотребления по аккаунту, а не рассматривать каждый откат как отдельную статью расходов. Клиент, который делает чарджбэк дважды, говорит вам то, чего не сказал первый возврат.

Как связать это по методу RefundHalt

Модель невелика, когда вы держите все части. Слушайте VoidedPurchaseNotification в реальном времени, чтобы ничто не ждало целые сутки. Вызывайте Voided Purchases API как источник истины, с ключом по orderId, чтобы продления подписки никогда не путались. Читайте voidedSource и voidedReason, чтобы чарджбэк обрабатывался иначе, чем возврат из-за передумавшего покупателя. Опрашивайте по расписанию, достаточно плотному, чтобы окно в 30 дней никогда не укусило, и возвращайте с включённой опцией отзыва всякий раз, когда ваше намерение состоит в том, чтобы обрезать доступ.

Это та часть, которую RefundHalt выполняет за вас. Он обрабатывает уведомления в реальном времени, сверяет каждое аннулирование с API, отзывает именно тот заказ, а не весь продукт, и отделяет банковский чарджбэк от обычного возврата, чтобы дорогие были помечены, а не погребены. Вы получаете отозванный доступ за секунды и запись о том, кто, что и почему аннулировал, без необходимости самим поднимать конвейер Pub/Sub и задачу опроса.