Leia o código de motivo de reembolso que o seu servidor já recebe, e ele te diz se você deve consertar o seu app ou brigar com o cliente

Quando a Apple ou o Google reembolsa um dos seus clientes, o dinheiro normalmente já foi antes de você ter voz. O que chega ao seu servidor depois parece um recibo, e a maioria das equipes trata como tal. É mais do que isso. Todo reembolso carrega um código de motivo de reembolso, e é a única parte de um reembolso que você ainda pode ler depois que a decisão foi tomada. O Google Play informa que o reembolso foi um estorno, ou um pedido por arrependimento, ou uma compra que o seu próprio app nunca confirmou. A Apple informa se o reembolso culpou algo dentro do seu app. Leia esse código e um reembolso deixa de ser uma linha em um relatório e vira uma instrução: conserte isto, conteste isto, ou deixe este passar. Aqui está o que cada código significa, como triá-los, e quanto cada um custa.

O que é de fato um código de motivo de reembolso

Um código de motivo de reembolso é o rótulo da própria loja para o motivo pelo qual uma compra foi revertida. Você não o define e não pode discutir com ele. Ele chega anexado ao reembolso após o fato, e as duas lojas o expõem em formatos diferentes e com resolução muito diferente.

O Google Play estampa um motivo e uma origem em cada anulação

A Voided Purchases API do Google Play retorna um registro por compra revertida, e cada registro carrega dois inteiros que importam. O voidedReason diz por que a compra foi anulada. O voidedSource diz quem deu início a isso. Juntos, eles transformam um reembolso simples em uma frase: este pedido foi anulado por causa de um estorno, iniciado pelo Google, ou anulado por arrependimento, iniciado pelo usuário. Você lê isso consultando a API ou assinando a notificação em tempo real para desenvolvedores que dispara quando uma anulação chega. De qualquer forma, os dois números são a carga que vale a pena guardar.

A Apple dá um sinal mais estreito, mas afiado

A Apple não te entrega um motivo de nove valores. Em uma transação reembolsada, a Apple define o revocationReason como um de dois valores. Um 1 significa que a App Store reembolsou a transação por causa de um problema real ou percebido dentro do seu app. Um 0 significa que ela reembolsou por outro motivo, por exemplo uma compra acidental. O campo aparece apenas em transações que foram reembolsadas ou revogadas, junto com uma revocationDate, dentro das informações assinadas da transação na App Store Server Notification REFUND. Dois valores não é muito, mas o que importa, um 1, é a Apple te dizendo que o reembolso foi sobre o seu produto, não sobre a mudança de ideia do cliente.

Os nove motivos que o Google Play te dá

O voidedReason do Google é o mais rico dos dois, e cada valor vale a pena conhecer de imediato porque cada um aponta para um lugar diferente. Aqui está o conjunto completo, direto do recurso VoidedPurchase, com o que cada código está de fato te dizendo para fazer.

O voidedSource te diz quem puxou o gatilho

Ao lado do motivo fica o voidedSource, e ele responde a uma pergunta diferente: quem reverteu isto. Um 0 significa que o usuário fez, por autoatendimento ou pelo banco. Um 1 significa que o desenvolvedor fez, ou seja, você ou suas próprias ferramentas emitindo um reembolso. Um 2 significa que o Google fez, por julgamento próprio, incluindo o reembolso automático de uma compra não confirmada. Quando você vê um pico de anulações, a origem é o primeiro corte. Uma parede de origem 2 é o Google agindo sobre a sua conta, e isso normalmente é um sinal que aponta de volta para a sua integração, e não para os seus clientes.

Classifique cada reembolso em consertar, contestar ou aceitar

O motivo de um código ser útil é que ele te diz qual de três respostas um reembolso merece. A maioria das equipes trata todos os reembolsos da mesma forma e gasta esforço com os que nunca poderá vencer. Os códigos se dividem de forma clara.

Consertar: os reembolsos que o seu produto causou

Alguns códigos são relatórios de bug vestidos de reembolso. Defeituoso (3) e não recebido (2) no Google, e um revocationReason de 1 na Apple, todos dizem a mesma coisa: o cliente pagou e o seu app não entregou. Compra não confirmada (8) é o mais claro destes porque a falha está inteiramente no seu código de cobrança. Estes são os reembolsos mais baratos de eliminar, porque você os elimina consertando algo que é seu, não convencendo ninguém. Uma contagem crescente nesta pilha é um defeito de produto com um valor em dinheiro anexado.

Contestar: os reembolsos que alguém está manipulando

Fraude (5), fraude amigável (6) e estorno (7) são as disputas. Fraude pura (5) não é o seu cliente e não é receita que você algum dia iria manter. Fraude amigável (6), em que o comprador recebeu exatamente o que pagou e depois contestou, é a única disputa que a sua evidência ainda pode mover, e o estorno (7) é onde essa evidência é enviada. Quando um destes chega, você revoga o acesso se ainda não o fez, e onde há uma janela de revisão aberta, você a responde com o que sabe sobre a conta.

Aceitar: os reembolsos que nunca foram seus para impedir

Arrependimento (1) e compra acidental (4) são a própria mudança de ideia do cliente. O revocationReason de 0 da Apple também fica aqui. Nenhum recurso falhou e nenhuma fraude ocorreu. Você pode suavizar o balde de acidentais com uma confirmação de compra mais clara, mas não pode discutir um reembolso por arrependimento, e o tempo gasto tentando é tempo tirado da pilha de consertos, onde o dinheiro realmente está.

A pegadinha dos 30 dias que torna os códigos de motivo fáceis de perder

Há um limite rígido do lado do Google que transforma isto de um recurso de relatório em um prazo. Se você não está capturando os códigos continuamente, você está perdendo eles.

A Voided Purchases API só olha 30 dias para trás

O Google é explícito: a API só pode mostrar compras anuladas dos últimos 30 dias. Anulações mais antigas não são retornadas, não importa qual startTime você passe, e o próprio valor de startTime não pode ser definido mais cedo do que 30 dias atrás. Pior para uma integração ingênua, a janela de 30 dias é medida por quando os sistemas do Google veem uma compra como anulada, não por quando a compra foi feita ou mesmo pelo voidedTimeMillis no registro. Então um código de motivo de reembolso que você não puxa dentro dessa janela se foi, e uma tarefa de exportação mensal com qualquer lacuna vai silenciosamente descartar anulações que foi lenta demais para capturar.

Quanto os códigos de motivo valem em dinheiro

Dois códigos carregam um preço específico, e lê-los é como você coloca um número em problemas que de outra forma se escondem dentro de uma taxa de reembolso agregada.

Um código é uma conta que você mesmo escreveu

O voidedReason 8, compra não confirmada, é o exemplo mais claro de um reembolso que você causou. O Google Play exige que o seu app confirme uma compra dentro de três dias após conceder o direito, e se você não o fizer, o Google reembolsa automaticamente o pedido e revoga o item. Toda anulação estampada com 8 é uma venda real, de um cliente que queria o produto, devolvida porque uma chamada para confirmar a compra nunca disparou. O valor perdido é o preço total da venda mais a computação, chamadas de API e armazenamento que você já gastou para entregá-la. Este não é um reembolso que você negocia. É um bug que você fecha, e o código é como você o encontra.

O código de estorno agora carrega uma taxa

O voidedReason 7, estorno, mudou de custo em 3 de agosto de 2026. Para pedidos do Google Play feitos nessa data ou depois, um estorno perdido custa ao desenvolvedor o preço da compra menos a taxa de serviço do Play, mais a taxa de estorno do banco, enquanto o Google cobre apenas a sua própria taxa de serviço. Como as taxas de estorno são fixas e os preços dos produtos não são, em uma compra dentro do app barata a taxa sozinha pode exceder o que o cliente pagou. Contar as suas anulações de código 7 agora é contar um item de despesa, não apenas uma venda perdida, que é exatamente por que o balde de estornos merece a sua própria linha em qualquer relatório de reembolsos que você construir.

Como a Apple e o Google se alinham

As duas lojas respondem à mesma pergunta em resoluções diferentes, então um relatório de reembolsos entre lojas tem que normalizá-las em vez de esperar que coincidam.

As lojas nunca vão te dar o mesmo código para o mesmo reembolso, e tudo bem. O que importa é que ambas te entregam um motivo legível por máquina, e ambas recompensam uma equipe que o lê. O único bit da Apple te diz quando um reembolso é culpa do seu produto. Os nove motivos do Google e sua sinalização de origem te dizem qual bug de produto, qual disputa e qual lacuna de cobrança autoinfligida você está olhando. Nenhum código impede um reembolso. Ambos te dizem o que fazer para que o próximo não aconteça.

A RefundHalt captura o código de motivo em cada reembolso no momento em que ele chega, em ambas as lojas, e o mantém bem dentro da janela de 30 dias do Google para que nada escape. Ela classifica cada anulação em consertar, contestar ou aceitar, para que um pico no código 3 defeituoso chegue a você como um alerta de produto e um pico no código 8 não confirmado chegue a você como um bug de integração, não como uma queda vaga na receita. Ela responde ao CONSUMPTION_REQUEST da Apple dentro de 12 horas e à revisão de estorno do Google Play dentro de 24, e revoga o acesso no momento em que um reembolso ou estorno chega. Você não pode mudar o código que uma loja estampa em um reembolso. Você pode garantir que lê cada um, e age sobre os que são de fato seus para consertar.