Imagine a seguinte situação. Um cliente compra seu plano anual, usa por uma semana e depois pede o dinheiro de volta à Apple. Você descobre isso quando seu pagamento chega menor. Ninguém perguntou nada a você. Ou pelo menos é o que parece.
Na verdade, a Apple frequentemente pergunta, sim. Ela envia ao seu servidor uma mensagem chamada CONSUMPTION_REQUEST, e quer saber como o cliente realmente usou o que comprou. Se seu servidor não estiver escutando, a Apple decide sem você. Este guia percorre o processo de reembolso da App Store para desenvolvedores, passo a passo, e aponta onde as pessoas costumam travar. Para uma visão mais ampla sobre defesa contra reembolsos no iOS, a página de defesa de reembolsos da App Store da RefundSensor também aborda o assunto.
Resposta Rápida
Uma notificação CONSUMPTION_REQUEST é a forma que a Apple usa para pedir detalhes de uso quando um cliente solicita um reembolso. Se o cliente concordou em compartilhar os dados, seu servidor deve chamar a Send Consumption Information Axz`PI dentro de 12 horas e informar entrega e uso. A Apple avalia essas informações e toma a decisão final. Você não pode aprovar um reembolso nem garantir o resultado.
O Que É o CONSUMPTION_REQUEST da Apple?
CONSUMPTION_REQUEST é um tipo de notificação dentro do App Store Server Notifications V2. A Apple o envia sempre que um cliente inicia uma solicitação de reembolso, e ele cobre todos os tipos de produto: consumíveis, não consumíveis, assinaturas não renováveis e assinaturas de renovação automática.
Pense nisso como uma pergunta, não uma ordem. A Apple não está dizendo para você reembolsar ninguém. Ela está perguntando o que você sabe. A Apple ainda toma a decisão final, e sua resposta é apenas um dos fatores que ela considera.
Como Funciona o Fluxo de Reembolso da Apple
Duas coisas acontecem aqui, e as pessoas costumam confundi-las. Receber a notificação é automático. Enviar as informações de consumo de volta só acontece se o seu servidor fizer isso.
O cliente solicita um reembolso à Apple.
A Apple envia um CONSUMPTION_REQUEST para a URL de notificação V2 do seu servidor.
Seu servidor verifica se esse cliente concordou em compartilhar dados de uso.
Se sim, seu servidor envia os detalhes de consumo dentro de 12 horas.
A Apple toma sua decisão. Se conceder o reembolso, uma notificação REFUND é enviada a seguir.
Guia de Implementação Passo a Passo
Veja a configuração do início ao fim.
Adicione sua URL de notificação. No App Store Connect, informe a URL HTTPS do seu servidor e escolha a Versão 2.
Responda rápido. Devolva um status entre 200 e 206. Um 40x ou 50x faz a Apple tentar novamente.
Verifique a assinatura. Os payloads V2 vêm assinados. Verifique antes de ler qualquer coisa dentro deles.
Encontre o cliente. Associe a transação a um usuário no seu próprio banco de dados.
Verifique o consentimento. Sem consentimento, sem resposta.
Chame a API. Envie os dados com uma requisição da App Store Server API, autenticada com uma chave In-App Purchase do App Store Connect.
Registre tudo. Mantenha um registro do que você enviou e quando.
Como Responder a uma Solicitação de Reembolso da Apple como Desenvolvedor
Sempre comece pelo consentimento. Depois disso, diga à Apple o que realmente aconteceu. O valor aqui vem de dados específicos e honestos, então não os infle.
Veja dois casos.
Um jogador compra um pacote de moedas e consome a maior parte em um dia. Informe o uso intenso. Pedir à Apple que negue é uma preferência razoável.
Um assinante paga por um ano, mas seu servidor estava fora do ar e o conteúdo nunca carregou. Informe que não houve entrega. Nesse caso, conceder o reembolso pode ser a resposta honesta.
Sua preferência de reembolso é apenas uma sugestão. A Apple não é obrigada a seguir.
A Send Consumption Information API da Apple Explicada
O endpoint Send Consumption Information é uma requisição PUT vinculada a um ID de transação (/inApps/v2/transactions/consumption/{transactionId}). Você o chama depois que um CONSUMPTION_REQUEST chega, e a Apple espera a resposta dentro de 12 horas.
O corpo é um objeto ConsumptionRequest com cinco campos:
customerConsented: o cliente concordou em compartilhar dados? Precisa ser true. Caso contrário, a Apple rejeita a chamada com um erro HTTP 400.
deliveryStatus: seu app entregou uma compra funcional?
sampleContentProvided: você ofereceu uma amostra gratuita ou teste antes?
consumptionPercentage: quanto foi usado, em miliunidades.
refundPreference: o resultado que você gostaria.
Algumas regras pegam as pessoas desprevenidas. Se deliveryStatus não for DELIVERED, defina consumptionPercentage como 0 ou a requisição falha. Para uma assinatura de renovação automática com GRANT_PRORATED, deixe consumptionPercentage de fora, já que a Apple calcula isso por conta própria. E o consentimento é responsabilidade sua. A Apple também diz para não usar o prompt de App Tracking Transparency para isso.
Integração com o App Store Server Notifications V2
OApp Store Server Notifications V2 é como a Apple chega até o seu servidor. Você vai precisar de uma URL HTTPS segura que aceite TLS 1.2 ou versões posteriores.
CONSUMPTION_REQUEST é só um entre muitos tipos. Outros, como REFUND e REFUND_REVERSED, informam como um caso terminou. Dê a cada tipo seu próprio handler para que o código de reembolso não fique misturado com o código de renovação. Quer ver o lado do App Store Connect em ação? O guia de configuração da Apple da Refund Sensor aborda as chaves e a URL de notificação.
Erros Comuns a Evitar
Parar na notificação. Um CONSUMPTION_REQUEST não faz nada até que seu servidor envie dados de volta.
Ignorar o consentimento. Sem concordância do cliente, não há resposta.
Perder as 12 horas. Essas notificações chegam durante a noite e nos fins de semana. Use uma fila e configure alertas.
Enviar combinações que não funcionam. Uma porcentagem de uso em uma compra que não foi entregue vai falhar.
Pular a verificação de assinatura. Verifique primeiro, confie depois.
Responder lentamente. Devolva um código de sucesso rapidamente e faça o trabalho pesado em segundo plano, ou a Apple continuará tentando novamente.
Nenhuma forma de encontrar o usuário. Se você não conseguir associar uma transação a um cliente, não terá nada real para reportar.
Como Automatizar os Fluxos de Reembolso da App Store
Ninguém quer ficar de olho em um relógio de 12 horas manualmente. Se você quiser automatizar os fluxos de reembolso da App Store, divida o trabalho em partes pequenas:
Aceite a notificação e devolva um código de sucesso imediatamente.
Coloque o evento em uma fila.
Um worker verifica o evento, encontra o usuário e checa o consentimento.
O worker monta a requisição a partir dos dados de uso armazenados e chama a API.
Registre o resultado e alerte alguém se falhar.
Você obtém respostas consistentes, uma trilha de auditoria clara e ninguém precisa ficar acordado às 3h da manhã. Você pode construir isso você mesmo ou entregar o pipeline para um serviço como a RefundSensor.
Boas Práticas para Desenvolvedores
Armazene dados reais de uso: sessões, créditos gastos, conteúdo acessado. Você não pode reportar números que nunca manteve.
Adicione uma etapa clara de consentimento aos seus termos ou onboarding, e registre quando ele foi dado.
Escreva suas regras de reembolso uma vez e coloque-as em código, em vez de decidir caso a caso.
Teste com notificações de sandbox antes de ir para produção.
Vincule um token de conta a cada compra para que você possa identificar o comprador mais tarde. Este guia de appAccountToken explica como fazer isso.
Revise os resultados de reembolso uma vez por mês. Picos estranhos podem indicar um recurso com problema ou um paywall confuso.
Conclusão
O fluxo de reembolso da Apple se resume a duas partes. A Apple envia o CONSUMPTION_REQUEST, e você decide se vai responder. Se o cliente consentiu, envie dados honestos através da Send Consumption Information API dentro de 12 horas. A Apple ainda é quem decide.
Um bom primeiro passo: confirme que sua URL de notificação V2 está ativa e que seu servidor consegue associar uma transação a um usuário. Essas duas verificações evitam muita dor de cabeça depois.
Perguntas frequentes
Uma mensagem V2 que a Apple envia quando um cliente solicita um reembolso. Ela pede detalhes de uso.
A Apple pede uma resposta dentro de 12 horas após a notificação.
Sim. Sem ele, não responda. Uma requisição com customerConsented definido como qualquer valor diferente de true é rejeitada.
Não necessariamente. A Apple usa seus dados para embasar a decisão, mas é ela quem decide.
Consumíveis, não consumíveis, assinaturas não renováveis e assinaturas de renovação automática.
