Se o seu app ainda usa App Store Server Notifications V1, a Apple nunca consulta você sobre reembolsos de assinaturas

A versão 1 do App Store Server Notifications ainda entrega reembolsos, mas deixa de fora a única notificação que permite contestar um reembolso de assinatura. A Apple descontinuou o V1 em 5 de junho de 2023, junto com o endpoint verifyReceipt, e desde então adicionou todos os recursos de reembolso apenas ao V2. Se as configurações do App Store Connect ainda mostram Version 1, a Apple pode decidir um reembolso de assinatura sem nunca enviar um CONSUMPTION_REQUEST ao seu servidor. Você não perde uma disputa. Você nunca é chamado para ela.

O que significa a descontinuação do App Store Server Notifications V1 pela Apple

Descontinuado não quer dizer desligado. Um engenheiro da Apple escreveu nos fóruns de desenvolvedores em junho de 2023 que o verifyReceipt e as notificações V1 continuarão funcionando até que uma data de desativação seja anunciada, que essa data ainda não tinha sido definida e que os desenvolvedores serão avisados com antecedência. Mais de três anos depois, o App Store Connect ainda oferece "Version 1 (deprecated)" como opção quando você define a URL do servidor.

O que a descontinuação significa, na prática, é um congelamento. Todas as mudanças no changelog de notificações da Apple desde junho de 2023 são mudanças do V2: campos novos na transação assinada, novos tipos de notificação, os dados de compromisso de 12 meses adicionados em abril de 2026. Um servidor V1 não vê nada disso.

Quais sinais de reembolso um servidor V1 nunca recebe

Veja como os mesmos eventos de reembolso chegam a um servidor V1 e a um servidor V2, de acordo com a documentação da Apple para cada versão.

O V1 ainda recebe CONSUMPTION_REQUEST?

Sim, para consumíveis. A referência do V1 da Apple descreve CONSUMPTION_REQUEST como a notificação enviada quando um cliente inicia uma solicitação de reembolso de uma compra no app consumível. Um engenheiro da Apple confirmou nos fóruns em 2023 que as solicitações de consumo do V1 são disparadas para reembolsos elegíveis. A lacuna está nas assinaturas. O changelog da Apple data as solicitações de consumo de assinaturas em 11 de abril de 2024, no V2, e a documentação do Send Consumption Information diz que a Apple envia a solicitação pelo seu endpoint V2.

Por que o CANCEL no V1 é fácil de interpretar errado

No V1, quando a Apple reembolsa uma assinatura, o tipo de notificação é CANCEL, muitas vezes acompanhado de DID_CHANGE_RENEWAL_STATUS. Muitos servidores tratam qualquer cancelamento como um cliente desativando a renovação automática, o que mantém o acesso ativo até o fim do período. O V2 elimina a ambiguidade. Um reembolso chega como REFUND, e um cliente desativando a renovação chega como DID_CHANGE_RENEWAL_STATUS com o subtipo AUTO_RENEW_DISABLED.

Quanto custa, em dinheiro, continuar no V1

A Apple decide todos os reembolsos da App Store. O CONSUMPTION_REQUEST é o único momento em que seus dados de uso chegam a essa decisão, e a Apple pede que você responda em até 12 horas. No V1, os reembolsos de assinaturas pulam essa etapa.

Veja um exemplo com números ilustrativos. Digamos que seu app venda uma assinatura mensal de $9.99 que inclui gerações de imagens com IA. Um assinante faz 400 gerações em um mês, e cada uma custa dinheiro de verdade em inferência do modelo. Depois ele pede um reembolso à Apple.

O pagamento que você perde é a sua parte, não o preço de vitrine. A Apple paga 70% do preço de uma assinatura, menos os impostos aplicáveis, durante o primeiro ano de serviço pago de um assinante, e 85% depois disso ou para membros do App Store Small Business Program. A conta de computação não diminui junto. Inferência, chamadas a APIs de terceiros e armazenamento de arquivos foram pagos quando o cliente os usou.

As duas notificações de resultado que faltam também custam dinheiro. Sem REFUND_REVERSED, um servidor que revogou o acesso por causa de um reembolso nunca o restaura quando a Apple reverte o reembolso, então um cliente pagante continua bloqueado e escreve para o suporte. Sem REFUND_DECLINED, você não consegue distinguir um reembolso ainda pendente de um que a Apple recusou.

Como migrar do V1 para o V2 sem perder nenhum reembolso

Migrar para o V2 é uma mudança no servidor mais uma configuração. A própria orientação da Apple nos fóruns, de um App Store Commerce Engineer em dezembro de 2025, explica o que acontece no dia da troca.

Crie o endpoint V2 antes de mudar a configuração

• Aceite um POST cujo corpo traga um signedPayload. Os payloads do V2 são JWS assinados pela Apple, então verifique a assinatura antes de confiar em qualquer coisa do conteúdo. A App Store Server Library da Apple faz isso por você.
• Mapeie o tratamento de CANCEL para REFUND, e trate REFUND_DECLINED e REFUND_REVERSED como casos novos.
• Responda ao CONSUMPTION_REQUEST de assinaturas com Send Consumption Information, e apenas quando o cliente tiver consentido em compartilhar dados com a Apple. A Apple diz que, sem consentimento, você não deve responder.
• Retorne HTTP 200 a 206 em caso de sucesso. Qualquer 40x ou 50x faz a Apple tentar de novo.

Mude a configuração no App Store Connect

No App Store Connect, abra seu app, escolha App Information em General, encontre App Store Server Notifications e defina a Production Server URL como seu endpoint V2, com Version 2 selecionada. Faça o mesmo antes com a URL de sandbox se quiser testar, e use Request a Test Notification para confirmar que seu servidor responde.

Mantenha o handler V1 ativo por cerca de três dias

Depois da troca, as notificações novas chegam no formato V2 imediatamente, para todas as assinaturas, antigas ou novas. As notificações V1 que já estão em nova tentativa continuam chegando no formato V1 até serem entregues ou esgotarem as tentativas. A Apple estima a última tentativa V1 possível em cerca de 78 horas, que são 6 mais 24 mais 48. Deixe o handler antigo rodando além desse prazo e depois remova-o.

Aproveite para substituir o verifyReceipt

O verifyReceipt foi descontinuado no mesmo dia. Ele ainda responde, mas a Apple orienta os servidores a usar a App Store Server API. Get Transaction Info retorna uma transação assinada, Get Transaction History retorna o histórico de um cliente e Get Refund History lista todas as compras reembolsadas de um cliente. Junto com as notificações V2, eles cobrem o que a maioria dos servidores fazia com recibos, incluindo o campo cancellation_date que antes marcava um reembolso em um recibo.

O RefundHalt se conecta ao App Store Server Notifications V2 e responde a cada CONSUMPTION_REQUEST dentro da janela de 12 horas, usando o uso que seu app já registra. Se você ainda está no V1, a troca é o passo que torna tudo isso possível.