Anexe um appAccountToken a cada compra na App Store, ou você não conseguirá defender o reembolso

Um cliente pede um reembolso à Apple, a Apple envia ao seu servidor um CONSUMPTION_REQUEST, e você tem doze horas para responder com dados reais sobre como aquela pessoa usou o produto. Então você abre a notificação e percebe que não faz ideia de quem ela é. A transação carrega um originalTransactionId e um id de produto, mas nada que aponte para a conta no seu próprio banco de dados. Essa lacuna é exatamente o que o appAccountToken fecha, e se você não o configurou no momento da compra, não consegue fechá-la depois para aquela venda.

O appAccountToken é um UUID que você anexa a uma compra para que a transação resultante da App Store carregue um ponteiro de volta ao usuário exato no seu sistema. Configure-o, e cada pergunta de reembolso que a Apple fizer sobre aquele cliente chegará com a identidade dele anexada. Pule essa etapa, e você estará adivinhando. Aqui está o que é o campo, como configurá-lo, o novo endpoint que resgata as compras feitas fora do seu app, e quanto o vínculo perdido realmente custa quando um reembolso chega.

O que o appAccountToken realmente é

O appAccountToken é um UUID opaco que você gera e passa ao StoreKit no momento da compra. A Apple o armazena na transação e o retorna nas informações da transação daquela compra, e ele fica lá. Nas palavras da Apple, é "o UUID que associa a transação à conta do usuário no seu próprio serviço". A única regra de formatação é que ele precisa ser um UUID. A Apple não o lê, não valida a que ele corresponde, e não se importa com o que ele significa do seu lado. É um vínculo que você controla.

Como ele vive na transação, ele volta a todos os lugares para onde a transação vai. A transação assinada em uma notificação de servidor, a resposta Get Transaction Info da App Store Server API, e cada renovação de uma cadeia de assinatura carregam o mesmo token se você o configurou na compra original. Um UUID, anexado uma vez, acompanha a cobrança do cliente por toda a duração do relacionamento.

Precisa ser um UUID de verdade, ou ele desaparece silenciosamente

A única regra que a Apple exige é o formato. O StoreKit 2 requer um UUID de RFC 4122. Se você passar uma string concatenada, um id inteiro ou um endereço de e-mail, o StoreKit não lança erro. Ele descarta o valor e a transação volta com o appAccountToken em nil. Os desenvolvedores esbarram nisso constantemente, e o sintoma é sempre o mesmo, alguma variação de "appAccountToken is missing in the transaction payload" nos próprios fóruns da Apple, quase sempre porque o valor passado não era um UUID válido. Gere um UUID de verdade no servidor, armazene-o vinculado à conta, e nunca entregue outra coisa ao StoreKit.

Como configurá-lo no momento da compra

No StoreKit 2 é uma única opção de compra. Gere o UUID no seu servidor quando o usuário se cadastra ou chega pela primeira vez ao checkout, armazene-o no registro da conta dele, e passe esse mesmo valor para a chamada de compra.

A assinatura é Product.PurchaseOption.appAccountToken(_ token: UUID), e uma compra fica assim try await product.purchase(options: [.appAccountToken(token)]). Quando a transação volta, verificada pela App Store Server API ou entregue por uma notificação de servidor, ela carrega aquele UUID, e seu servidor localiza o cliente em uma única consulta.

Use um token estável por conta

Não gere um token novo para cada compra do mesmo usuário. A Apple retorna o token nas renovações, nas novas tentativas de cobrança e nos upgrades da mesma cadeia, então um UUID estável por conta te dá um fio limpo desde a primeira compra até cada evento futuro. Um token que muda a cada compra quebra esse fio e frustra todo o propósito. Uma conta, um token, reutilizado toda vez que aquela conta compra.

O endpoint que resgata as compras fora do app

Até 2025 havia um buraco. Se um cliente resgatava um código de oferta ou fazia uma compra dentro do app promovida direto da App Store, seu app nunca executava o fluxo de compra, então não havia onde configurar o appAccountToken. Essas transações chegavam anônimas e assim permaneciam.

A WWDC 2025 fechou a lacuna com o endpoint Set App Account Token. Seu servidor chama PUT /inApps/v1/transactions/{originalTransactionId}/appAccountToken na App Store Server API com o UUID no corpo, e a Apple configura o token naquela transação. Funciona para todos os tipos de produto, cobre os resgates de códigos de oferta e as compras promovidas, e o valor que você envia sobrescreve qualquer token já presente na transação. Agora você pode associar uma compra depois do fato, a partir do seu servidor, sem que ela jamais passe pelo seu app.

Onde o vínculo perdido custa dinheiro a você

O objetivo do token não são registros organizados. É que a única pergunta de reembolso da Apple para desenvolvedores, o CONSUMPTION_REQUEST, só tem resposta se você conseguir encontrar o cliente a que ela se refere.

Quando um comprador solicita um reembolso de um consumível ou de uma assinatura não renovável, a Apple envia ao seu servidor uma notificação CONSUMPTION_REQUEST e te dá doze horas para responder com Send Consumption Information. Sua resposta são dados sobre aquele cliente específico: quanto do produto ele consumiu, o tempo de conta dele, o gasto ao longo da vida, o status de entrega. O appAccountToken é ele próprio um dos campos dessa solicitação, e mais importante, é como a transação da notificação se associa à conta cujo uso você está prestes a descrever. Sem token, sem consulta, sem resposta precisa.

Quanto uma resposta em branco realmente custa

Um reembolso não identificado força uma escolha ruim. Você pode responder à solicitação de consumo com nada, o que é lido como baixo consumo e empurra a Apple na direção de conceder o reembolso, inclusive a clientes que usaram o produto intensamente. Ou você pode adivinhar. De qualquer forma você está reembolsando compras que tinha provas para defender, e já pagou o custo real de entregá-las.

Esse custo não é o preço de venda. Um consumível que executou um lote de chamadas à API de um modelo, gerou imagens, exportou um vídeo ou disparou um repasse a um criador gastou dinheiro real no momento em que foi entregue. O reembolso devolve o pagamento do cliente. Não devolve a fatura do fornecedor. Multiplique um cliente não identificável por cada reembolso que ele abre, e por cada reembolsador em série que conta com o fato de você não saber quem ele é, e o token que você pulou se torna a linha de código mais cara que você nunca escreveu.

A mesma ideia existe no Android, sob outro nome

O Google Play resolve o problema idêntico com o setObfuscatedAccountId, que anexa um identificador de conta a uma compra para que a revisão de estorno do Google via orders.reviewrefund possa ser respondida contra um usuário real. Loja diferente, mecânica diferente, a mesma lição: anexe a identidade no momento da compra ou você não conseguirá defender a disputa depois. Na App Store, essa ferramenta é o appAccountToken, e ele precisa ser um UUID.

Três hábitos que mantêm o token no lugar

• Gere um UUID por conta e armazene-o. Um token estável por cliente, criado quando ele se cadastra ou no primeiro checkout, salvo no registro dele e reutilizado em cada compra.
• Valide antes de passá-lo. Confirme que o valor é um UUID de verdade no seu código de compra, para que um id malformado nunca possa virar silenciosamente um token nil na transação.
• Preencha as compras feitas fora do app. Quando uma notificação de servidor chega para um resgate de código de oferta ou uma compra promovida sem token, chame o endpoint Set App Account Token para anexar o correto.

Faça essas três coisas e cada transação que a Apple te enviar, incluindo os pedidos de reembolso, chegará já vinculada ao cliente a quem pertence.

Essa é a base da qual o RefundHalt depende. Nós lemos o appAccountToken de cada transação e notificação de servidor, associamos ao uso que já rastreamos para aquela conta, e respondemos à solicitação de consumo da Apple dentro da janela de doze horas com os números reais do cliente. O token é o fio. Configure-o uma vez e sua defesa de reembolsos terá algo em que se segurar.