A revisão de estorno do Google Play te dá 24 horas para reagir, veja o que enviar

Quando o banco de um cliente reverte uma cobrança do Google Play, o Google Play não apenas devolve o dinheiro e segue em frente. Ele envia ao seu servidor uma PendingRefundReviewNotification e inicia um relógio de 24 horas. Responda essa notificação por meio da ReviewRefund API com uma preferência de reembolso e evidências do que o cliente realmente usou, e o Google Play incorpora a sua contribuição na forma como contesta o estorno. Fique em silêncio, e a disputa é resolvida sem uma palavra da única parte que sabe como o produto foi consumido.

A revisão de estorno do Google Play é o único fluxo de reembolso do Android que pede evidências a você, a contraparte direta do CONSUMPTION_REQUEST da Apple. Agora importa mais do que antes. A partir de 3 de agosto de 2026, o Google Play transfere o custo dos estornos para os desenvolvedores, então uma disputa que você deixa de responder sai da sua conta, não da do Google. Aqui está exatamente o que a notificação carrega, o que você envia de volta, os campos que compõem as suas evidências e onde o silêncio vira dinheiro.

O que é de fato uma revisão de estorno do Google Play

Um estorno não é um pedido de reembolso. O cliente vai ao banco ou à rede de cartões e contesta a cobrança, e o banco retira os fundos. O Google Play trata a maioria desses casos por conta própria. Para um subconjunto, ele abre uma revisão e pergunta a você primeiro, porque você tem informações que o Google não tem: se o pedido foi entregue e quanto dele o cliente consumiu. Essa revisão é o fluxo por trás da ReviewRefund API.

Este é o único lugar no sistema de reembolso do Android onde as suas evidências mudam o resultado. Todos os outros caminhos de reembolso do Google Play rodam sem você. Um cliente pode fazer um reembolso por autoatendimento dentro de 48 horas da compra, o suporte pode conceder um, e uma compra não confirmada é reembolsada automaticamente, tudo decidido pelo Google. A revisão de estorno é a exceção, e vale a pena tratá-la como a única conversa de reembolso da qual você realmente pode participar.

É a versão Android da janela de evidências da Apple

Duas lojas, dois fluxos que pedem evidências ao desenvolvedor, e essa é a lista inteira. A Apple envia um CONSUMPTION_REQUEST e te dá 12 horas para responder com Send Consumption Information. O Google Play envia uma PendingRefundReviewNotification e te dá 24 horas para responder com orders.reviewrefund. A mecânica difere, mas a lição é idêntica: quando a loja pergunta o que o cliente usou, uma resposta precisa é a diferença entre manter a venda e devolvê-la.

Uma diferença importa na prática. A carga de consumo da Apple são cinco campos numéricos e nada mais. As evidências do Google Play são mais ricas. Você pode enviar uma porcentagem de consumo mais uma lista de eventos de uso individuais, cada um com um carimbo de data e hora, um identificador de conta e até um endereço IP e uma localização aproximada. O Google Play te dá mais espaço para descrever a entrega, o que significa mais espaço para ser convincente.

O relógio de 24 horas e como a notificação chega até você

A revisão chega como uma Real Time Developer Notification no seu topic do Cloud Pub/Sub, o mesmo canal que entrega os seus eventos de assinatura e compra. A mensagem é uma carga codificada em base64 com um objeto pendingRefundReviewNotification dentro dela. O relógio começa quando essa notificação é publicada, não quando você a lê, então um consumidor que faz polling uma vez por dia é um consumidor que perde disputas.

PendingRefundReviewNotification, campo por campo

A notificação é pequena. Ela diz qual pedido está em revisão, te entrega o token que você precisa citar de volta e nomeia a razão. Aqui está cada campo que ela carrega.

Só um estorno abre uma revisão pendente

O refundReason de uma revisão pendente é sempre CHARGEBACK, entregue como o inteiro 7. Existem outras razões de reembolso no mundo do Google Play, mas elas não chegam a você por este fluxo, porque você não tem voz nelas. Se você vê uma PendingRefundReviewNotification, um banco reverteu uma cobrança e o Google Play está decidindo se a contesta. Esse é o único gatilho.

O que você envia de volta pela ReviewRefund API

Você responde com um único POST para orders.reviewrefund. O caminho completo é POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/orders/{orderId}:reviewrefund, autorizado com o scope https://www.googleapis.com/auth/androidpublisher, o mesmo scope de OAuth que a sua integração com a Play Developer API já usa. Um sucesso retorna um corpo vazio com HTTP 200.

O corpo é onde o seu caso vive. Você ecoa o pendingRefundToken da notificação, declara uma preferência de reembolso e anexa evidências de consumo.

Sua preferência de reembolso é uma recomendação, não um veredito

O campo refundPreference aceita um de três valores, e é um conselho para o Google Play, não uma decisão final. O Google continua dono do resultado. Mas é um conselho respaldado por dados que o Google não pode ver por conta própria, então tem peso.

Os campos de evidência que sustentam um DECLINE

Um DECLINE isolado é uma alegação sem prova. Os campos de consumo são a prova. consumptionPercentageMilliunits é um inteiro em milésimos, então 100000 diz que o cliente consumiu 100 percent do que comprou e 50000 diz metade. consumptionUsageEvents é um array opcional onde cada evento pode carregar um obfuscatedAccountId, um obfuscatedProfileId, um consumptionTime, um ipAddress, um consumptionItemDescription e uma location aproximada. sampleContentProvided é um booleano para o caso em que você deu ao cliente uma amostra grátis do conteúdo pago. Juntos, eles dizem, no próprio esquema do Google Play, que o produto foi entregue e usado.

Sua primeira chamada é a sua única chamada

O Google Play registra a primeira chamada de ReviewRefund que você faz contra uma notificação e ignora toda chamada depois dela, ainda que continue retornando um status OK. Não há rascunho nem revisão. Se a sua primeira resposta é um NEUTRAL apressado sem evidências porque o seu pipeline não estava pronto, essa é a resposta que fica registrada, e a chamada posterior com o histórico de consumo completo é descartada em silêncio. Monte a resposta completa antes de enviar qualquer coisa.

Quanto a revisão te custa em dinheiro

Por anos, um estorno perdido no Google Play custava ao desenvolvedor a venda e pouco mais, porque o Google Play absorvia as taxas subsequentes. Isso acaba em 3 de agosto de 2026. Para pedidos feitos depois dessa data, o Google Play compartilha o custo do estorno com os desenvolvedores, e a parte do desenvolvedor é o preço de compra menos a taxa de serviço do Play, mais a taxa de estorno associada cobrada pela instituição financeira. O Google Play continua cobrindo a parcela da taxa de serviço. A taxa do banco é um peso novo no seu lado do livro-caixa.

O reembolso nunca é o número real

A disputa devolve o pagamento do cliente, mas o pagamento nunca foi o seu único custo. Um vídeo gerado, um lote de chamadas à API de um modelo, um repasse a um criador, armazenamento que você provisionou, todo esse dinheiro saiu da sua conta no momento em que o pedido foi entregue, e nada disso volta com o estorno. Agora some a taxa de estorno do banco por cima. Você está pagando a fatura do fornecedor, reembolsando a venda e cobrindo a taxa da disputa, três custos por um pedido que você tinha as evidências para defender.

A escala que o Google está combatendo

O Google Play diz que bloqueou US$3.4B de fraude e abuso em 2025 e está adicionando detecção de fraude ao longo de 2026. A mudança no compartilhamento de custos é parte do mesmo esforço: dar aos desenvolvedores uma razão para alimentar o sistema com evidências, e o sistema contesta mais das disputas ilegítimas. A ReviewRefund API é como as suas evidências entram. Uma resposta vazia é um voto para deixar um estorno de fraude amigável se sustentar às suas custas.

Como estar pronto antes de a notificação chegar

A janela de 24 horas não é o problema. O problema é que as evidências de que você precisa têm que existir antes da disputa, capturadas no momento da compra e do consumo, não reconstruídas depois que um token aparece. Uma equipe que começa a coletar dados quando a notificação chega já perdeu.

Anexe a identidade no momento da compra

Defina um obfuscatedAccountId com setObfuscatedAccountId em cada compra, para que o id de conta da notificação aponte diretamente para um usuário no seu sistema. Mantenha-o como um hash, de 64 caracteres ou menos, nunca e-mail em texto claro ou outros dados pessoais, porque identificadores em texto claro fazem as compras serem bloqueadas. Sem esse vínculo você não consegue conectar o pendingRefundToken a um histórico de uso real, e o seu DECLINE não tem nada por trás.

Registre o consumo à medida que ele acontece

Registre o que um pedido pago entregou, quando e para quem, em uma forma que você possa transformar em consumptionPercentageMilliunits e consumptionUsageEvents sob demanda.

• Carimbe com data e hora cada unidade de consumo, para que consumptionTime em cada evento seja real, não estimado.
• Acompanhe a entrega em relação à compra, para que você possa declarar uma porcentagem de consumo com confiança em vez de adivinhar.
• Mantenha os identificadores de conta e perfil ao lado do uso, para que um evento se monte em uma única consulta quando o token chegar.
• Capture o IP da requisição e a localização aproximada se você os tiver, já que o Google Play aceita ambos como campos de evento.

Responda dentro da janela, automaticamente

Uma janela de 24 horas é confortável para uma máquina e brutal para um humano que precisa estar acordado e atento. A resposta deveria ser automática: entra a notificação, a conta é consultada, o consumo é montado, sai uma chamada de ReviewRefund, tudo sem uma pessoa no circuito. Essa é a parte que o RefundHalt roda por você. Nós escutamos a PendingRefundReviewNotification, casamos o pedido com o uso que já rastreamos para aquela conta, e respondemos orders.reviewrefund dentro da janela com uma preferência de reembolso e evidências de consumo reais. O token é o fio, e as evidências são o caso. Tenha os dois prontos e a única conversa de reembolso da qual você pode participar é uma que você pode vencer.