Uma notificação de compra anulada permite que seu servidor do Google Play revogue o acesso no instante em que um reembolso é concluído

Um reembolso no Google Play não precisa ser algo que você descobre depois em um relatório. O Google Play pode enviar ao seu servidor uma notificação de compra anulada no instante em que uma compra é anulada, seja porque o comprador fez um reembolso de autoatendimento, um agente de suporte concedeu um, um banco forçou um estorno ou você mesmo reembolsou o pedido com o sinalizador de revogação ativado. A mensagem é minúscula, ela nomeia a compra exata e carrega uma instrução, devolver o direito de acesso, porque o dinheiro já se foi.

O que é, de fato, uma notificação de compra anulada

Uma notificação de compra anulada é um tipo de Real-time Developer Notifications do Google Play, ou RTDN. A RTDN é um canal de push. O Google publica uma mensagem em um tópico do Cloud Pub/Sub de sua propriedade, e seu backend a recebe momentos após o evento, em vez de descobrir na próxima consulta agendada. Esse é todo o objetivo da notificação de compra anulada em relação ao antigo caminho de pull: você fica sabendo do reembolso conforme ele acontece, não horas depois.

O caminho de pull ainda existe e ainda importa. A Voided Purchases API permite que seu servidor solicite, no seu próprio cronograma, a lista de compras que foram anuladas em um intervalo de tempo. Os dois são complementares. A notificação avisa no instante em que uma compra muda de estado; a API permite reconciliar em massa e recuperar qualquer coisa que uma mensagem perdida teria deixado para trás.

Ela viaja dentro de uma Real-time Developer Notification

A notificação de compra anulada nunca chega sozinha. Ela fica dentro de um invólucro DeveloperNotification, e esse invólucro é entregue como uma única string codificada em base64 no campo data da mensagem do Pub/Sub. Seu handler decodifica essa string para JSON antes de conseguir ler qualquer coisa. O invólucro sempre nomeia o app e o horário do evento, e contém exatamente um objeto de notificação entre os cinco que o Google define. Eles são mutuamente exclusivos, então uma mensagem que carrega um voidedPurchaseNotification não carregará também um evento de assinatura ou de compra única.

Os quatro campos que ela carrega

Remova o invólucro e a própria notificação de compra anulada são quatro campos. Isso é deliberadamente enxuto. A posição do Google é que, se tudo o que você precisa é encontrar a compra certa e ajustar o direito de acesso, esses quatro bastam, e você não precisa retornar a nenhuma API para agir.

productType informa o que foi anulado

productType é um inteiro pequeno, e ele decide qual dos seus caminhos de revogação tomar. A anulação de uma assinatura precisa desfazer o acesso contínuo; a anulação de uma compra única apenas remove um único direito de acesso.

refundType informa quanto foi devolvido

refundType separa uma reversão total e limpa de uma parcial. O caso parcial é restrito. Ele só aparece quando uma compra única de múltiplas quantidades teve parte, mas não toda, da sua quantidade reembolsada.

Ative-a primeiro, ou ela nunca chega

As notificações de compra anulada não fluem por padrão. Você ativa a RTDN uma vez, no Play Console, e a aponta para um tópico do Pub/Sub que você controla. A opção fica em Monetize, depois Monetization setup, na seção Real-time developer notifications no topo da página. Marque Enable real-time notifications, depois cole o nome completo do seu tópico no formato projects/{project_id}/topics/{topic_name} e use Send Test Message para confirmar que o canal funciona antes de confiar nele.

O seletor de conteúdo é onde as pessoas deixam escapar as compras anuladas. As duas opções as incluem, então você não pode desativar acidentalmente os reembolsos enquanto mantém as assinaturas.

• Get notifications for subscriptions and all voided purchases. Você recebe os eventos de assinatura e todas as compras anuladas, mas não os eventos de compra de produtos únicos.
• Get all notifications for subscriptions and one-time products. Você recebe o acima mais os eventos de produtos únicos, como ONE_TIME_PRODUCT_PURCHASED e ONE_TIME_PRODUCT_CANCELED.

Quanto isso custa a você, em dinheiro

Uma anulação é uma perda que já está contabilizada quando a notificação chega até você. O preço da venda se foi, e também tudo o que você gastou atendendo esse cliente. Se ele gerou imagens, fez chamadas aos seus modelos, consumiu armazenamento ou acionou um pagamento a terceiros, esses custos foram pagos em dinheiro real e não voltam com o reembolso. A notificação não pode recuperar nada disso. O que ela pode fazer é estancar o sangramento daqui para frente, que é toda a razão para agir rápido sobre ela.

O sangramento é pior nas assinaturas e pior nos estornos. Uma assinatura que você não revoga continua custando para ser servida, mês após mês, para um cliente que não paga mais. E um estorno é o tipo mais caro de anulação. A partir de August 3, 2026, a documentação do Google afirma que um estorno repassa ao desenvolvedor o preço da compra mais a taxa do banco. A notificação de compra anulada é frequentemente o primeiro lugar em que seus próprios sistemas ficam sabendo que um estorno foi concluído, então um handler que revoga na hora é o que impede que uma venda perdida se transforme em uma venda perdida mais semanas de serviço gratuito.

Como lidar com uma notificação de compra anulada, passo a passo

Verifique e desduplique a mensagem

• Confirme que a mensagem do Pub/Sub veio do Google e visa o tópico que você configurou, depois decodifique o campo data em base64 para obter o JSON de DeveloperNotification.
• Use o messageId do Pub/Sub para descartar duplicatas. O Google avisa que a mesma notificação pode ser entregue mais de uma vez, então trate a reentrega como normal e torne seu handler idempotente.
• Confirme (acknowledge) a mensagem somente depois de tê-la registrado com segurança, para que uma falha no meio do handler não perca o evento.

Localize a compra

• Faça a correspondência do purchaseToken com a compra que você armazenou quando concedeu o direito de acesso pela primeira vez. Recorra ao orderId para buscas de suporte e reconciliação manual.
• Leia productType para escolher o caminho de revogação de assinatura ou de compra única, e leia refundType para decidir entre uma revogação total e uma parcial.

Revogue e registre

• Remova o direito de acesso. Para um reembolso total, corte o acesso ao item. Para um reembolso parcial baseado em quantidade, reduza a quantidade concedida pelo valor reembolsado e deixe o restante intacto.
• Registre o que você fez e quando, indexado por purchaseToken e orderId. Esse registro é o que permite responder a um ticket de suporte depois, e o que permite que a Voided Purchases API reconcilie de forma limpa com o seu próprio estado.

Onde ela se encaixa entre os outros sinais de reembolso

Uma notificação de compra anulada é um aviso, não uma negociação. Ela informa um desfecho que já está decidido. Vale a pena vê-la ao lado dos sinais com os quais é fácil confundi-la, porque apenas alguns deles chegam a pedir a sua versão da história.

A ideia a reter é simples. Entre as duas lojas existem exatamente dois fluxos de reembolso em que o desenvolvedor tem voz, o CONSUMPTION_REQUEST da Apple e a revisão de estorno do Google Play. Uma notificação de compra anulada não é nenhum dos dois. Quando ela chega até você, a decisão já ficou para trás e a única coisa que resta em suas mãos é a rapidez com que você revoga.