A detecção de reembolsos no StoreKit 2 se resume a uma propriedade da transação, e é a revocationDate

A maioria dos apps fica sabendo de um reembolso da Apple pelo seu servidor, por uma App Store Server Notification, e nunca percebe que o mesmo reembolso já está dentro do app. Ele está na transação, em uma propriedade chamada revocationDate, e lê-la permite que seu app corte o acesso de um cliente reembolsado na próxima vez que ele abrir, em vez de esperar por um job do backend. A detecção de reembolsos do StoreKit 2 é um sinal do lado do cliente que a maioria das equipes pula. Aqui você vê exatamente onde um reembolso aparece no dispositivo, o que ele diz, o que não diz, e por que ele deve ficar ao lado das suas notificações de servidor e não no lugar delas.

Onde um reembolso aparece dentro do StoreKit 2

O StoreKit 2 entrega as transações como valores assinados, e um reembolso não apaga a transação. Ele a marca. Duas propriedades da Transaction carregam a marca, e ambas permanecem nil por toda a vida de uma compra saudável. Quando uma delas deixa de ser nil, a App Store retomou a compra.

revocationDate é o campo que muda

revocationDate é um Date opcional. A própria descrição da Apple é exata: é a data em que a App Store reembolsou a transação ou a revogou do Family Sharing. Para uma compra que ainda é válida, é nil. No momento em que um reembolso é processado, ela guarda o carimbo de tempo desse reembolso. Essa única verificação, se revocationDate não é nil, é toda a detecção de reembolsos do lado do cliente. Todo o resto é nuance empilhada em cima.

revocationReason diz por que a Apple a retirou

revocationReason fica ao lado da data e explica a causa. O StoreKit lhe dá dois valores que importam para reembolsos. developerIssue significa que o cliente disse à Apple que o reembolso se deveu a um problema real ou percebido no seu app. other cobre todos os demais motivos. Um terceiro valor, upgradedToBundle, não é um reembolso; ele sinaliza uma transação que a App Store revogou porque o cliente passou para um pacote de assinatura. Leia o motivo antes de agir, porque developerIssue é o que vale a pena contar: um grupo deles é o seu próprio produto dizendo onde ele falhou.

currentEntitlements já descarta uma compra reembolsada

Você nem sempre precisa ler os campos de revogação você mesmo. Transaction.currentEntitlements é a sequência de compras a que um cliente ainda tem direito agora, e a Apple a monta para deixar de fora as que você não deveria honrar. Um produto que a App Store reembolsou ou revogou não aparece nela. Nem as assinaturas expiradas, nem os consumíveis, que somem no momento em que são usados.

Isso faz de currentEntitlements o filtro mais limpo para o acesso. Pergunte a ela o que o cliente possui, conceda exatamente isso, e um reembolso remove o direito por você sem uma única verificação de revocationDate. Os campos de revogação são para quando você quer o detalhe, a data e o motivo, para registrar o evento ou reagir a ele. A lista de direitos é para a pergunta simples de manter ou não as luzes acesas.

A detecção de reembolsos do StoreKit 2 na prática, desde a inicialização e enquanto o app roda

Há dois momentos em que seu app pode captar um reembolso no dispositivo, e eles precisam de código diferente. Um é enquanto o app está aberto e um reembolso acontece ao vivo ou em outro dispositivo. O outro é na inicialização, colocando em dia tudo o que mudou enquanto você estava fechado. Falhe no segundo e a sua detecção de reembolsos do StoreKit 2 tem um buraco exatamente onde a maioria dos reembolsos cai, porque os clientes raramente estão com o seu app aberto quando pedem um.

Comece a escutar na inicialização ou você perde os reembolsos que aconteceram enquanto estava fechado

Transaction.updates é a sequência assíncrona que emite uma transação sempre que o sistema cria ou atualiza uma fora do seu app ou em outro dispositivo, um reembolso incluído. A instrução da Apple é direta: inicie um Task que a percorra assim que seu app iniciar, ou você pode perder as transações que ela entrega uma única vez na inicialização. Um reembolso que chegou de madrugada aparece por updates na próxima vez que o app abre, mas só se já houver um ouvinte rodando para recebê-lo. Sem ouvinte, sem evento, e o reembolso fica invisível até que outra coisa o reconcilie.

Uma compra no mesmo dispositivo não chega por updates

Uma armadilha pega quem testa reembolsos na mão. Uma compra normal feita no mesmo dispositivo não chega por updates; o StoreKit a retorna direto do resultado da chamada de compra. updates é para as mudanças fora de banda: reembolsos, aprovações de Ask to Buy, resgates de códigos de oferta e compras feitas em outro lugar. Então construa o seu tratamento de reembolsos em torno de updates e currentEntitlements, não em torno do fluxo de compra, porque o reembolso nunca voltará pelo caminho que a venda tomou.

O que a detecção do lado do cliente não pode fazer por você

Ler reembolsos no dispositivo é rápido e é de graça, mas tem um teto, e fingir que não tem é como a receita vaza. O dispositivo só sabe o que o StoreKit lhe disse, e o StoreKit só fala enquanto o seu app está rodando. Um cliente que recebe um reembolso e nunca mais abre o seu app é um cliente que a sua verificação do lado do cliente nunca vê.

Uma revocationDate nem sempre é um reembolso

O mesmo campo muda por causa do Family Sharing. Quando um cliente perde o acesso a uma compra compartilhada, porque o organizador o removeu ou o compartilhamento terminou, essa transação também recebe uma revocationDate. Então uma data não nil significa que o cliente não tem mais esta compra, que é exatamente o que você precisa para o controle de acesso, mas nem sempre significa que voltou dinheiro. Se você está contando reembolsos para a receita, separe as revogações de Family Sharing das reais antes de confiar no número.

Um reembolso pode ser revertido

Um reembolso nem sempre é final. A Apple pode reverter um, e quando o faz, os campos de revogação são removidos da transação e a compra volta a ser válida. Se você cortou o acesso no reembolso, espera-se que o restaure na reversão. No dispositivo isso aparece como outro evento de updates com uma transação limpa; no seu servidor é uma notificação distinta, REFUND_REVERSED. Trate só o reembolso e você deixará um cliente pagante ilhado, sem acesso e com um recibo que funciona.

Quanto uma revogação tardia realmente custa

Um reembolso raramente é só o preço de venda saindo da sua conta. Quando ele é liquidado, você normalmente já gastou dinheiro de verdade atendendo aquela compra, e esse gasto não volta. As imagens geradas custam minutos de GPU. As respostas do chat custam chamadas à API do modelo que foram cobradas de você por token. Os uploads custam armazenamento que você ainda paga para manter. Se a compra financiou um pagamento a um criador, esse dinheiro já saiu pela porta. Nada disso é revertido com o reembolso.

A detecção do lado do cliente encolhe a janela na única parte que você ainda pode controlar, que é o gasto futuro. Quanto antes você souber que uma compra foi reembolsada, antes você para de atendê-la. Mas o dispositivo só avisa enquanto o app está aberto, então um usuário reembolsado que nunca volta mantém o acesso do lado do servidor que você concedeu, custando a você em silêncio toda vez que um job em segundo plano ou um dispositivo sincronizado age em nome dele. O cliente torna a revogação rápida. Ele não a torna garantida.

Use o cliente para a rapidez e o servidor para a verdade

O design limpo usa os dois sinais para aquilo em que cada um é bom. No dispositivo, Transaction.updates e currentEntitlements dão a você uma reação local e instantânea no momento em que um cliente reembolsado abre o app, boa para a interface e para finalizar mudanças de direito sem uma ida e volta. No servidor, as App Store Server Notifications V2 enviam uma mensagem REFUND que chega independentemente de o app ser reaberto ou não, que é o único sinal que interrompe de forma confiável o gasto do seu backend em uma conta reembolsada.

Conecte os sinais do dispositivo para o cliente que está com o telefone na mão, e a notificação do servidor para o que não está. O reembolso aparece nos dois lugares de propósito. Ler só um deles é como uma conta reembolsada continua custando a você depois de a venda já ter ido embora.