Existe um endpoint que retorna todo o histórico de reembolsos da App Store de um cliente, e aqui está o que ele devolve

A Apple mantém um registro consultável de cada reembolso que concedeu na conta de um cliente para o seu app, e uma chamada o retorna. O endpoint é o Get Refund History, parte da App Store Server API, e ele te entrega o histórico completo de reembolsos da App Store desse cliente como uma lista de transações assinadas. Você passa um id de transação, recebe de volta o que a Apple reembolsou, e concilia com o que você ainda tem ligado.

Aqui está por que vale a pena. Um reembolso que você nunca vê é um reembolso que você continua pagando. O dinheiro já se foi, mas a conta permanece ativa, e a cada hora que fica você continua gastando com computação, chamadas à API do modelo, armazenamento e qualquer repasse ligado a esse cliente. Suas notificações de reembolso deveriam detectar isso no momento em que acontece. O Get Refund History é a rede de segurança para quando elas não detectam, depois de uma queda, de um deploy que perdeu um webhook, ou de um caso de suporte em que você precisa do quadro completo em uma única chamada.

O que o endpoint de histórico de reembolsos da App Store retorna

Você chama GET /inApps/v2/refund/lookup/{transactionId} na App Store Server API, assinada com o mesmo JWT que você usa em todas as outras chamadas a ela. O id de transação no caminho pode ser qualquer transação do cliente. A Apple o lê como uma identidade, não como um filtro, e retorna as compras reembolsadas desse cliente em todo o seu app: consumíveis, não consumíveis, assinaturas renováveis automaticamente e não renováveis igualmente. A V1 mais antiga desse endpoint retornava até 50 reembolsos em uma única resposta e está obsoleta. A versão atual pagina, então você lida com clientes de históricos longos sem uma carga gigante.

A resposta são três campos

O que uma transação reembolsada te diz

Cada entrada em signedTransactions é um JWS. Verifique-o contra a cadeia de certificados da Apple, decodifique-o, e você tem um payload de transação comum com os campos de reembolso preenchidos. Estes são os que importam aqui.

O token revision é como você para de reler a lista inteira

A forma ingênua de usar este endpoint é consultar um cliente e percorrer todas as páginas toda vez. Isso funciona, e em um cliente com cinquenta reembolsos são cinquenta linhas que você já conhecia mais a única nova. O token revision existe para eliminar esse desperdício. Cada resposta carrega um revision. Quando hasMore é verdadeiro, você o passa de volta para obter a próxima página. Quando você chega ao fim, guarda o último revision que viu.

O que este endpoint não fará

Há uma expectativa a abandonar antes de construir sobre ele. O Get Refund History é por cliente, não por app. Você não pode pedir a ele todos os reembolsos que seu app recebeu na semana passada. Ele responde a uma pergunta, quais reembolsos esta conta tem, e você precisa chegar com um id de transação dessa conta para perguntar. Os desenvolvedores batem nessa parede o tempo todo e saem procurando um endpoint de reembolsos de todo o app que não existe.

A visão de todo o app fica em outro lugar. Seu feed de App Store Server Notifications envia uma notificação REFUND no momento em que a Apple concede cada uma, e o Get Notification History permite reproduzir esse feed filtrado pelos tipos de reembolso em um intervalo de datas. Então a divisão é limpa. As notificações e o histórico delas te dão o fluxo de todo o app. O Get Refund History te dá a lista autoritativa de uma conta, sob demanda, que é o que você quer em um balcão de suporte ou depois de uma queda.

Quanto um reembolso não detectado te custa em dinheiro

O endpoint é encanamento. A conta é o motivo pelo qual você instala o cano. Cada reembolso naquela lista é dinheiro já devolvido, e a única variável que resta sob seu controle é por quanto tempo você continua gastando com uma conta que não paga mais.

Você continua pagando para atender uma conta reembolsada

O preço da compra some no instante em que a Apple concede o reembolso. O que continua rodando é o custo da entrega. Para um app que faz trabalho real por usuário, isso é computação, chamadas à API do modelo, armazenamento e qualquer repasse a criador ou parceiro ligado ao uso dele. Um cliente reembolsado cujo acesso você nunca corta é uma assinatura que você banca do próprio bolso. Conciliar contra o Get Refund History e revogar com base no que você encontra é como você desliga esse medidor quando uma notificação escapou.

Um motivo de reembolso 1 é um relatório de defeito disfarçado

revocationReason te custa em dobro se você o ignora. O primeiro custo é o reembolso em si. O segundo é cada reembolso futuro pela mesma causa. Quando um produto continua voltando com revocationReason 1, um problema real ou percebido no seu app, a Apple está te entregando uma amostra rotulada do que faz os clientes pedirem o dinheiro de volta. Acompanhe a tendência por produto e você poderá tapar o vazamento em vez de pagá-lo um reembolso de cada vez.

Detectar tarde ainda é melhor do que não detectar

Um estorno é definitivo com o banco e, na outra loja, agora carrega uma taxa que o desenvolvedor absorve. Um reembolso da App Store não é isso. Está liquidado, mas o direito é seu para revogar no momento em que você souber. Então mesmo um reembolso que você encontra dias atrasado por este endpoint vale a pena encontrar. Você não pode recuperar o dinheiro, mas pode parar o gasto que ainda corria por trás dele.

Como isso se encaixa com as notificações, e com o Google

Pense nas peças como um único sistema. A notificação REFUND é o sinal ao vivo, enviado ao seu servidor conforme a Apple decide. O Get Refund History é a fonte da verdade baseada em extração para um único cliente, a chamada que você faz quando o envio falhou ou quando uma pessoa precisa da conta completa à frente. No lado do Google Play a forma é a mesma ideia com nomes diferentes: uma VoidedPurchaseNotification é enviada em tempo real, e a Voided Purchases API é a lista que você extrai. Ambas as lojas te dão um fluxo e um livro de registros. O erro é confiar apenas no fluxo, porque fluxos caem.

Configurando do jeito RefundHalt

O ciclo é pequeno depois que cada peça está no lugar. Pegue uma notificação REFUND como gatilho. Concilie contra o Get Refund History para que um webhook perdido nunca deixe uma conta reembolsada ativa. Decodifique cada transação, vincule-a por appAccountToken ou transactionId de volta ao seu usuário, leia revocationReason para que um reembolso por defeito seja sinalizado e não apenas arquivado, e revogue o direito exato em vez da conta inteira. Pagine com o token revision para ler os reembolsos novos, não os antigos.

Esta é a parte que o RefundHalt roda por você. Ele escuta as notificações de reembolso, recorre ao Get Refund History quando precisa da lista autoritativa, verifica cada transação assinada, revoga a compra precisa, e guarda o revision para que cada passagem leia apenas o que mudou. Você tem o acesso cortado em segundos e um registro limpo de quem foi reembolsado, por qual produto e por quê, sem precisar montar você mesmo o polling e a verificação JWS.