Use o Google Play RTDN para um tratamento rápido de eventos. Use a Voided Purchases API para verificar pedidos anulados e reconciliar seus registros. Para a maioria dos aplicativos pagos, a escolha mais segura é usar os dois.
Se você está planejando uma defesa de reembolso do Google Play para aplicativos, comece com essa divisão. Um caminho informa que algo mudou. O outro permite que seu servidor busque uma lista de compras anuladas e verifique o que ele deixou passar.
A escolha não é exatamente entre dois sistemas de notificação. O Google Play RTDN envia mensagens por push através do Cloud Pub/Sub. A Voided Purchases API é uma API de pull: seu backend é que a chama.
Nenhuma delas, por si só, impede que alguém solicite um reembolso. O valor das duas está em detectar mudanças, verificar pedidos e garantir que o acesso pago corresponda ao estado da compra.
Principais pontos
Use o RTDN para reagir prontamente a eventos de compra e assinatura.
Use a lista de compras anuladas como um segundo caminho para verificar os pedidos afetados.
Não trate uma assinatura cancelada como prova de um reembolso.
Faça com que os dois caminhos usem a mesma lógica segura de atualização de acesso.
Mantenha a revisão pendente de chargeback separada de uma anulação concluída.
O que é o Google Play RTDN?
O Google Play Real-Time Developer Notifications, geralmente chamado de RTDN, envia eventos relacionados a compras para um tópico do Cloud Pub/Sub.
Seu backend recebe uma mensagem e a direciona para o worker correto. O tipo de mensagem importa. Uma renovação, um cancelamento e uma compra anulada não são o mesmo evento.
Para o rastreamento de reembolsos, preste atenção especial ao voidedPurchaseNotification. Ele inclui:
purchaseToken: vincula o evento a uma compra.
orderId: identifica o pedido afetado.
productType: identifica uma assinatura ou uma compra única.
refundType: diferencia uma anulação total de um reembolso parcial baseado em quantidade.
A referência do RTDN e as definições de eventos do Google explicam esses campos e os outros tipos de notificação.
O RTDN é útil quando você quer agir logo após uma mudança. Mas uma mensagem não é seu banco de dados completo de compras. Combine-a com os registros armazenados e recupere o estado de compra relevante quando necessário antes de alterar o acesso.
Um cancelamento de assinatura significa um reembolso?
Não. Um cliente pode interromper renovações futuras e ainda assim manter o acesso pago pelo restante do período atual.
Não crie uma regra que remova o acesso sempre que SUBSCRIPTION_CANCELED for recebido. Em vez disso, verifique o estado e a expiração da assinatura. A revogação e a expiração precisam de tratamento próprio.
O que é a Voided Purchases API?
A Google Play Voided Purchases API retorna uma lista de compras que foram canceladas, reembolsadas ou que sofreram chargeback dentro do escopo suportado.
Ela se aplica a pedidos únicos no aplicativo e a assinaturas. Seu servidor pode usar os resultados para verificar quais compras não devem mais conceder acesso.
A lista pode incluir o ID do pedido, o token de compra, o horário da anulação, a origem da anulação e o motivo da anulação. Para reembolsos parciais baseados em quantidade suportados, ela também pode incluir a quantidade reembolsada.
O guia da Voided Purchases API do Google documenta uma retrospectiva de 30 dias. Não se trata de um arquivo permanente de reembolsos. Salve os registros processados em seu próprio sistema.
Essa API é especialmente útil após uma interrupção do worker, um bug de roteamento ou uma lacuna em seus registros locais. Ela também oferece uma verificação de rotina em relação aos eventos que você processou.
RTDN vs Voided Purchases API: a diferença prática
Pergunta | Google Play RTDN | Voided Purchases API |
Como funciona? | O Google publica um evento no Pub/Sub. | Seu servidor solicita uma lista. |
Qual é sua função principal? | Tratamento imediato de mudanças no estado da compra. | Verificação e reconciliação de pedidos anulados. |
Ela cobre eventos além de reembolsos? | Sim, incluindo renovações e outros eventos de ciclo de vida. | Ela se concentra em compras anuladas. |
Ela pode ajudar após uma lacuna de processamento? | A recuperação do Pub/Sub depende da sua configuração e retenção. | Ela pode listar os registros disponíveis dentro da janela de 30 dias. |
Ela precisa de proteção contra duplicação? | Sim. | Sim, especialmente quando as verificações se sobrepõem ou compartilham eventos com o RTDN. |
A questão central não é qual ferramenta é melhor isoladamente. É qual falha cada ferramenta ajuda você a resolver.
O RTDN oferece um caminho rápido. A API oferece um caminho de verificação. Seu próprio banco de dados deve reunir os dois.
Qual deles seu aplicativo deve usar?
Use o RTDN quando a velocidade for importante
Um aplicativo pago não deve precisar esperar por uma verificação programada para notar uma mudança no estado da compra.
Use o RTDN quando seu aplicativo precisar de atualizações imediatas para assinaturas, compras únicas e pedidos anulados. Direcione cada evento por tipo, em vez de aplicar uma única regra de reembolso a todas as mensagens.
Use a API quando a integralidade for importante
Use verificações programadas da API para encontrar pedidos anulados que seu worker não aplicou aos seus registros.
Por exemplo, seu receptor pode ter aceitado uma mensagem, mas um bug pode ter impedido a atualização de acesso posterior. Corrigir apenas a entrega não resolverá essa lacuna local.
Use os dois para um fluxo de trabalho de reembolso em produção
Para a maioria dos aplicativos pagos, combine os dois. Faça com que ambos os caminhos alimentem um único handler compartilhado que verifica o pedido e aplica qualquer mudança com segurança.
Isso reduz o risco de um evento perdido deixar o acesso ativo. Também reduz o risco contrário: remover o acesso duas vezes para o mesmo reembolso.
Como detectar reembolsos do Google Play passo a passo
1. Mantenha um livro-razão de compras
Armazene o pacote do aplicativo, o token de compra, o ID do pedido, o produto, o mapeamento do usuário e a quantidade concedida. Um livro-razão é simplesmente um registro claro do que foi comprado e do acesso que isso concedeu.
Para assinaturas, armazene também os IDs de pedido de renovação. A referência do RTDN observa que cada renovação automática tem um novo ID de pedido. Um token de compra isolado não é suficiente para identificar todas as renovações afetadas.
2. Proteja e direcione as mensagens do RTDN
Configure o acesso ao Pub/Sub corretamente. Para entrega por push, verifique a solicitação autenticada. Para entrega por pull, restrinja quem pode ler a assinatura.
Decodifique a mensagem, verifique o nome do pacote e salve-a antes de executar tarefas mais lentas. Envie eventos de teste por todo o caminho, não apenas pelo endpoint receptor.
3. Execute uma verificação programada de compras anuladas
Chame o método de listagem com credenciais adequadas e permissões do Play Console. Percorra todas as páginas de resultados.
Duas configurações de consulta são fáceis de passar despercebidas:
type=1 inclui tanto compras únicas quanto assinaturas. O padrão, 0, inclui apenas compras únicas.
includeQuantityBasedPartialRefund=true inclui reembolsos parciais baseados em quantidade suportados. Seu padrão é false.
A referência do método voidedpurchases.list do Google cobre os campos de solicitação e paginação.
Use uma sobreposição modesta entre as verificações e elimine duplicatas dos resultados. Escolha a frequência de verificação com base no seu volume, nas suas cotas e em quanto atraso seu aplicativo pode aceitar. Não espere até a janela de retrospectiva estar quase no fim.
4. Aplique cada mudança apenas uma vez
Os dois caminhos podem relatar a mesma anulação. Construa um tratamento idempotente: executar a mesma mudança novamente não deve alterar o resultado.
Não use apenas o ID do pedido para descartar todos os eventos posteriores. Uma compra com múltiplas quantidades pode ter vários reembolsos parciais. Rastreie os ajustes processados e as quantidades reembolsadas para que um reembolso real posterior não seja perdido.
5. Monitore a lacuna, não apenas a contagem de mensagens
Rastreie a última verificação bem-sucedida, as páginas não concluídas, os erros do worker e os pedidos não correspondidos. Meça quanto tempo leva para atualizar o acesso após um evento confirmado.
Para um relatório mais amplo, veja nosso guia de ferramentas de rastreamento de reembolso e chargeback para aplicativos móveis.
Exemplo: um reembolso, dois caminhos de detecção
Este é um fluxo de trabalho hipotético, não um caso real relatado por um cliente.
Um jogador compra um pacote único que concede 500 moedas. A compra é posteriormente anulada por completo.
O RTDN envia uma mensagem de compra anulada. Seu worker localiza o pedido, verifica a concessão registrada e aplica sua política publicada às moedas vinculadas a essa compra.
Mais tarde, a verificação programada da API retorna o mesmo pedido. O handler compartilhado constata que o ajuste de anulação total já foi aplicado. Ele registra a correspondência e não realiza uma segunda dedução.
Agora suponha que o worker tenha falhado antes de aplicar a primeira mudança. A verificação encontra o pedido e dá ao seu sistema outro caminho para processá-lo.
Esse é o propósito de usar os dois. Não duas penalidades separadas, mas duas maneiras de chegar a um único resultado correto.
Se algumas moedas já tiverem sido gastas, não remova moedas às cegas de um pacote pago não relacionado. Use uma política clara, explique a ação e forneça um canal de suporte.
A revisão de reembolso pendente é um fluxo de trabalho separado
A documentação atual do Google também lista o pendingRefundReviewNotification para uma solicitação de chargeback que exige revisão do desenvolvedor.
Para esse evento, o Google orienta a fornecer uma sugestão de reembolso e evidências de uso da compra por meio do orders.reviewrefund em até 24 horas.
Não confunda isso com o voidedPurchaseNotification. Um se refere a uma revisão pendente. O outro relata uma compra que foi anulada.
A Voided Purchases API não substitui o tratamento de um evento de revisão pendente. Mantenha essa ramificação separada e não assuma que toda solicitação de reembolso a produz.
Reembolsos da App Store e vazamento de receita: o que os desenvolvedores precisam saber
O vazamento de receita não se limita a saber se uma loja devolve dinheiro. Também pode significar que seu backend continua concedendo acesso pago depois que a compra relevante já não o justifica.
Para equipes que atuam nas duas plataformas, o objetivo é semelhante: manter o dinheiro, o estado da compra e os registros de acesso alinhados. As ferramentas da loja e as regras de evento, porém, são diferentes. Não copie um fluxo de trabalho da Apple para o Google Play sem adaptações.
Nosso guia de gestão de receita de reembolsos da App Store aborda o problema mais amplo de gestão de receita. Para esta integração com o Google Play, concentre-se primeiro em anulações perdidas, deduções duplicadas e mudanças incorretas no acesso de assinaturas.
O que a prevenção de fraudes em reembolsos do Google Play pode e não pode fazer
A prevenção de fraudes em reembolsos do Google Play começa com registros sólidos e regras justas. Um pedido anulado não é prova de que o cliente agiu de forma desonesta.
Um usuário pode ter uma reclamação válida. Um pagamento pode falhar. Seu aplicativo pode ter entregado o item errado.
Use essas ferramentas para verificar os fatos e aplicar mudanças de acesso. Analise padrões repetidos dentro do contexto. Evite banimentos automáticos de contas com base em um único reembolso e permita que os clientes contestem erros.
Nem o RTDN nem a API de listagem garantem que você possa evitar, rejeitar ou reverter um reembolso.
Conclusão
A escolha entre RTDN e Voided Purchases API não é uma decisão excludente para a maioria dos aplicativos pagos.
Use o RTDN para reagir rapidamente. Use verificações programadas de compras anuladas para reconciliar registros. Envie os dois por meio de um único handler seguro e mantenha as revisões pendentes separadas das anulações concluídas.
Comece com um pequeno teste: envie uma anulação pelos dois caminhos e confirme que o acesso muda apenas uma vez. Depois, pare seu worker e verifique se seu caminho de recuperação detecta a lacuna.
Perguntas frequentes
O RTDN é mais adequado para o tratamento imediato de eventos. A API é mais adequada para verificações programadas de pedidos anulados. A maioria dos aplicativos pagos se beneficia de ambos.
Sim. Ele inclui uma notificação de compra anulada com detalhes do pedido e do tipo de reembolso. Trate esse evento separadamente de um cancelamento de assinatura.
Você pode detectar registros anulados disponíveis por meio de polling, mas a detecção espera até sua próxima verificação bem-sucedida. Você também perde o fluxo mais amplo de eventos de ciclo de vida do RTDN.
O Google documenta uma janela de 30 dias. Mantenha seus próprios registros para verificações de longo prazo e necessidades de suporte.
Sim. Habilite os resultados de reembolso parcial compatíveis nas solicitações de listagem. Rastreie as quantidades reembolsadas e considere a possibilidade de mais de um reembolso parcial em um pedido.
