Quando uma compra do Google Play é reembolsada ou estornada, a Voided Purchases API é como você fica sabendo

Um reembolso no Google Play não bate na sua porta. O dinheiro sai, o cliente continua com o app aberto e, a menos que você vá procurar, nada muda do seu lado. A Voided Purchases API é onde você vai procurar. Ela lhe entrega uma lista de pedidos que foram cancelados, reembolsados ou estornados, para que você possa revogar o acesso ao que o cliente não pagou mais. Aponte um job agendado para ela, leia a lista, corte o direito de acesso. Esse é o ciclo inteiro.

Há uma pegadinha que atrapalha a maioria das equipes, e ela não está no código. Apenas pedidos que foram revogados aparecem aqui. Se você reembolsar uma compra no Play Console sem marcar a opção de revogação, esse pedido nunca chega a esta API, e seu job roda limpo enquanto um cliente reembolsado mantém tudo o que você vendeu. Este texto percorre a API campo por campo, os números que a limitam e onde o dinheiro vaza quando você a ignora.

O que a Voided Purchases API realmente retorna

A API responde a uma pergunta: quais pedidos deste app foram anulados recentemente. Uma anulação abrange três desfechos que terminam com o cliente recebendo o dinheiro de volta. Um cancelamento, um reembolso ou um estorno. Ela se aplica a produtos avulsos dentro do app e a assinaturas, e você escolhe o escopo com um único parâmetro. Defina type como 0 e você obtém apenas as compras de produtos avulsos anuladas, que é o padrão. Defina como 1 e você obtém as compras avulsas anuladas e as compras de assinatura anuladas juntas.

Cada entrada na lista é um objeto de compra anulada. Os campos são poucos e cada um deles importa.

Os campos de uma compra anulada

Leia voidedReason antes de agir

voidedReason é o campo que transforma uma lista crua em uma decisão. Um reembolso por arrependimento do comprador e um estorno bancário caem na mesma lista, mas não são o mesmo evento, e os preços de agosto tornam um deles caro. Aqui está o conjunto completo.

A janela de 30 dias é a armadilha que esvazia sua lista

A Voided Purchases API só consegue mostrar compras anuladas dos últimos 30 dias. O parâmetro startTime tem como padrão o horário atual menos 30 dias, e não pode ser definido mais antigo que isso. endTime tem como padrão agora. Então o endpoint é uma janela móvel de um mês, não um arquivo.

A consequência é direta. Se seu job de consulta quebrar e ninguém perceber por cinco semanas, as anulações da primeira semana envelheceram e saíram da API. Não há chamada que as traga de volta. Você não revogará esses pedidos, e nem saberá que existiram, a menos que os tenha capturado de outra forma. A API é uma rede de segurança com um buraco do tamanho da sua pior interrupção.

A opção de revogação decide se um pedido sequer aparece

Este é o motivo mais comum de uma equipe relatar que a API está quebrada. Apenas pedidos revogados são retornados. Reembolsos iniciados pelo usuário, cancelamentos, estornos e reembolsos iniciados pelo Google são sempre revogados, então sempre aparecem. Um reembolso iniciado pelo desenvolvedor é diferente. Quando você mesmo reembolsa um pedido, pelo Play Console ou pela Orders API, você escolhe se também o revoga. Reembolse sem revogar, e o pedido fica acertado com o cliente, mas nunca aparece na Voided Purchases API.

A regra que decorre disso é simples. Se sua intenção é retirar o acesso, reembolse com a opção de revogação ativada. Caso contrário, você devolveu o dinheiro e deixou a porta aberta, e seu job de revogação, por melhor que seja escrito, não tem nada sobre o que agir.

Como fazer a consulta sem estourar a cota

O endpoint tem limite de taxa, e os limites são baixos o suficiente para que um loop ingênuo os atinja. Você tem 6.000 consultas por dia, contadas no horário do Pacífico, e no máximo 30 consultas em qualquer período de 30 segundos. Esse orçamento é adequado para consulta por janela e hostil a designs de uma requisição por pedido.

Janelas de consulta e o token de continuação

maxResults tem como padrão 1.000, que também é o teto. Quando uma janela contém mais de uma página de anulações, a resposta traz um objeto tokenPagination com um nextPageToken. Passe esse token de volta na próxima chamada para percorrer as páginas. Defina startTime e endTime para delimitar a janela que lhe interessa, avance pelas páginas até o token acabar, então avance a janela. Esse padrão mantém você dentro tanto do limite de rajada de 30 segundos quanto do limite diário.

As Real-time developer notifications fecham a brecha

Consultar todos os dias ainda deixa até um dia de cegueira, e a janela de 30 dias pune longos intervalos. As Real-time developer notifications eliminam o atraso. O Google publica uma VoidedPurchaseNotification em um tópico do Cloud Pub/Sub que você possui no momento em que uma compra é anulada, e seu backend a consome em segundos. A mensagem é pequena.

Quanto isso custa a você em dinheiro

A API é encanamento, mas o motivo para conectá-la é uma conta. Toda anulação naquela lista corresponde a um número real, e dois deles estão ficando mais caros.

A conta do estorno cai sobre você a partir de 3 de agosto de 2026

A partir de 3 de agosto de 2026, o Google transfere o custo de um estorno para o desenvolvedor. Você perde o valor da compra e ainda paga a taxa de estorno do banco por cima. Um voidedReason igual a 7 não é mais apenas uma venda perdida, é um item de linha com uma taxa anexada. Você não pode reverter um estorno, ele é final junto ao banco, mas pode estancar o sangramento depois dele. Capturar a anulação rapidamente permite revogar o direito de acesso e, para qualquer coisa que você ainda esteja entregando, parar de gastar com um cliente que foi reembolsado e depois teve a cobrança revertida.

Você continua pagando para atender um cliente reembolsado

O valor da compra some no momento em que uma anulação aparece. O que você ainda controla é o custo de continuar a entregar. A cada hora que um direito de acesso reembolsado permanece ativo, você continua pagando pelas coisas que o cliente não financia mais: computação, chamadas de API de modelos, armazenamento e qualquer repasse a criadores ou parceiros ligado ao uso dele. Um sistema de revogação movido por esta API é como você desliga esse medidor. Ignore-o, e você financia o produto para pessoas que a loja já ressarciu.

A fraude amistosa é um padrão que vale acompanhar

Um voidedReason igual a 5 ou 6 não é um caso isolado. Fraude e fraude amistosa se agrupam por conta, por dispositivo e às vezes por promoção. A API lhe dá o voidedSource e o voidedReason em cada anulação, o que basta para acompanhar o abuso por conta em vez de tratar cada reversão como um custo isolado. Um cliente que faz estorno duas vezes está lhe dizendo algo que o primeiro reembolso não disse.

Montando tudo do jeito RefundHalt

O modelo é pequeno quando você segura todas as peças. Escute a VoidedPurchaseNotification em tempo real para que nada espere um dia inteiro. Chame a Voided Purchases API como fonte da verdade, com chave em orderId para que as renovações de assinatura nunca se confundam. Leia o voidedSource e o voidedReason para que um estorno seja tratado de forma diferente de um reembolso por arrependimento. Faça a consulta em um cronograma apertado o suficiente para que a janela de 30 dias nunca morda, e reembolse com a opção de revogação ativada sempre que sua intenção for cortar o acesso.

Esta é a parte que o RefundHalt roda para você. Ele consome as notificações em tempo real, concilia cada anulação com a API, revoga o pedido exato em vez do produto inteiro e separa um estorno bancário de um reembolso comum para que os caros sejam sinalizados, não enterrados. Você tem o acesso revogado em segundos e um registro de quem anulou o quê e por quê, sem ter que montar você mesmo um pipeline de Pub/Sub e um job de consulta.