A Retention Messaging API da Apple coloca suas palavras na tela de cancelamento, mas os pedidos de reembolso nunca passam por ela

Assinantes que tocam em Cancelar em um iPhone agora podem ver uma mensagem escolhida por você, um plano mais barato ou um desconto, antes de confirmar. Essa é a Retention Messaging API da Apple, e é a primeira vez que um desenvolvedor tem voz na própria tela de cancelamento da Apple. Ela ainda é um pré-lançamento no qual você precisa pedir para entrar. Ela também tem um limite rígido que importa se você se preocupa com reembolsos: fala com quem está prestes a parar de pagar, não com quem está pedindo o dinheiro de volta. Esses pedidos chegam à Apple por outro caminho.

O que a Retention Messaging API da Apple faz

A Retention Messaging API é um serviço de servidor para servidor. Você envia à Apple, com antecedência, textos e imagens das mensagens, a Apple os revisa, e depois você escolhe qual mensagem aprovada um assinante vê quando está prestes a cancelar uma assinatura com renovação automática. A documentação da Apple lista quatro tipos de mensagem:

• Uma mensagem de texto, que pode incluir marcadores.
• Uma mensagem de texto com imagem.
• Uma mensagem de troca de plano, que sugere outra assinatura do mesmo grupo de assinaturas.
• Uma mensagem de oferta promocional, que oferece um preço com desconto no mesmo nível ou em outro, usando uma oferta promocional que você configura no App Store Connect e assina no seu servidor.

A mensagem aparece depois que o cliente toca em Cancel Subscription em uma página de detalhes da assinatura. Em seguida, a Apple mostra uma página Confirm Cancellation (Confirmar cancelamento). O cliente ainda pode cancelar, tocar em Keep Subscription (Manter assinatura) ou aceitar a oferta ou o plano que você sugeriu. Você não pode esconder a saída, e a Apple orienta os desenvolvedores a não enviar conteúdo enganoso ou impreciso.

Mensagens padrão e o fluxo em tempo real

Há duas formas de usar. A simples são as mensagens padrão: texto, com ou sem imagem ou marcadores, atribuído a cada produto e idioma. A mais completa é o fluxo em tempo real, em que a Apple chama um endpoint Get Retention Message no seu servidor e você responde com um ID de mensagem. Só o fluxo em tempo real pode mostrar mensagens de troca de plano e de oferta promocional.

Na prática, as mensagens padrão não são opcionais. A Apple as usa como alternativa sempre que uma chamada em tempo real falha, e não mostra nenhuma mensagem de retenção para um produto em um idioma que não tenha uma mensagem padrão.

O que a Apple informa ao seu servidor na chamada em tempo real

A requisição é um JWS assinado pela App Store. Decodificada, ela traz originalTransactionId, appAppleId, productId, userLocale, um requestIdentifier UUID, o ambiente e signedDate. A Apple pede que você verifique se o appAppleId corresponde ao seu app e que não responda se não corresponder. O originalTransactionId é a parte útil, porque permite consultar o que esse assinante realmente fez no seu app antes de escolher o que dizer.

Onde a mensagem de retenção aparece e onde não aparece

A Apple coloca a mensagem em uma única tela, a etapa Confirm Cancellation depois que o cliente toca em Cancel Subscription, por exemplo a partir de Apple Account > Subscriptions ou da página de uma assinatura na App Store. Essa tela trata de saber se a próxima renovação vai acontecer. Ela não mexe no dinheiro já cobrado.

Um pedido de reembolso é um ato separado. A página de suporte da Apple envia os clientes para reportaproblem.apple.com, onde eles escolhem “Request a refund” (Solicitar reembolso), selecionam um motivo e um item, e esperam de 24 a 48 horas por uma atualização. Dentro do seu app, o beginRefundRequest do StoreKit abre a folha de reembolso da Apple, e a Apple diz que a App Store leva até 48 horas para aprovar ou negar. Nenhum dos dois caminhos passa pela tela Confirm Cancellation.

Uma mensagem de retenção pode impedir um pedido de reembolso?

Não. O pedido de reembolso nunca chega à tela onde a mensagem fica. Um detalhe na documentação de notificações da Apple deixa isso concreto. Quando um cliente pede reembolso pelo seu app com a API de pedido de reembolso, a própria Apple desativa a renovação automática e envia DID_CHANGE_RENEWAL_STATUS com o subtipo AUTO_RENEW_DISABLED. Um cliente que cancela na página de ajustes de Assinaturas gera o mesmo tipo e subtipo. Seu servidor vê uma única notificação para dois clientes muito diferentes, e só um deles viu sua mensagem de retenção.

Se o pedido de reembolso seguir adiante, o canal de evidências é o CONSUMPTION_REQUEST. A Apple o envia para pedidos de reembolso de qualquer tipo de produto, e você tem 12 horas para responder com Send Consumption Information. Você só pode responder se o cliente deu consentimento. Depois, a decisão da Apple chega como uma notificação REFUND, ou como REFUND_DECLINED se a Apple recusar um reembolso que o cliente iniciou no seu app.

O Google Play tem uma API de mensagem de cancelamento?

Não na documentação do ciclo de vida de assinaturas do Google. Um assinante do Google Play cancela pela central de assinaturas do Play, mantém o acesso até o fim do ciclo de cobrança atual e pode tocar em Resubscribe (Assinar novamente) para desfazer antes disso, o que o Google chama de restauração. Você fica sabendo depois, por uma notificação SUBSCRIPTION_CANCELED, e o campo userInitiatedCancellation no recurso da assinatura informa por que o usuário saiu. A pausa, que segundo o Google vem ativada por padrão em todas as assinaturas, é a principal ferramenta nativa dele para reduzir o cancelamento voluntário.

Do lado dos reembolsos, o Google Play tem seu próprio canal de evidências. Uma PendingRefundReviewNotification chega quando um chargeback precisa de revisão do desenvolvedor, e você tem 24 horas para responder por orders.reviewrefund. Para pedidos feitos depois de 3 de agosto de 2026, quando um chargeback é aceito, o Google repassa ao desenvolvedor o preço da compra, menos a taxa de serviço do Play, mais as taxas de chargeback do banco.

Quanto a tela de cancelamento custa em dinheiro

As mensagens de retenção parecem gratuitas. Não são, e as contas chegam por três lados.

Processamento a cada visualização de página

A Apple chama seu endpoint quando um assinante ativo abre uma página de detalhes da assinatura com um botão Cancelar, não só quando ele cancela. Cada visita é uma requisição que seu servidor precisa autenticar, consultar e responder em 700 ms, ou a Apple recorre à mensagem padrão. Isso descarta uma função com cold start que às vezes leva dois segundos. Você paga por capacidade que fica sempre pronta, mais as leituras de banco de dados e as chamadas pagas a APIs de terceiros que sua lógica de decisão faz a cada requisição.

O desconto é receita que você escolheu não receber

Uma oferta promocional que mantém um assinante é dinheiro real preservado. Uma que vai para alguém que ficaria de qualquer jeito é puro desconto. Isto é uma ilustração, não um parâmetro de mercado. Um plano mensal de US$ 9,99 oferecido pela metade do preço por três meses abre mão de US$ 14,99 a cada oferta aceita. Se uma em cada três pessoas que aceitam teria ficado pagando o preço cheio, mil aceites custam cerca de US$ 5.000 em descontos dados a quem nunca precisou deles. O outro lado da conta são os assinantes que realmente estavam indo embora.

O reembolso que uma saída desagradável provoca

A Apple mantém o botão Cancel Subscription na página, então você não consegue prender ninguém, mas ainda pode ser irritante. Um cliente que se sente pressionado tem outra opção: pedir à Apple a devolução da última cobrança. Quando um reembolso acontece, o dinheiro volta, e o processamento, o armazenamento, as chamadas de API e eventuais pagamentos a afiliados ligados a esse assinante continuam gastos. São custos que nenhuma mensagem de retenção recupera.

Como usar mensagens de retenção sem aumentar sua taxa de reembolso

Trate a tela de cancelamento como um lugar para ser preciso, não esperto. Algumas regras a mantêm do lado certo da linha do reembolso:

• Decida por assinante. Use o originalTransactionId da requisição da Apple para consultar o uso recente. Ofereça desconto ou um plano mais barato para quem usa o produto. Mostre uma mensagem curta e honesta para quem não abre o app há semanas.
• Mantenha a resposta rápida. Calcule a decisão com antecedência sempre que seus dados de uso mudarem, para que a requisição em si seja uma única consulta que caiba com folga em 700 ms.
• Escreva uma mensagem padrão para cada produto e idioma. Sem ela, uma chamada que falha significa nenhuma mensagem.
• Acompanhe de perto o AUTO_RENEW_DISABLED. Se em seguida chegar um CONSUMPTION_REQUEST para o mesmo originalTransactionId, você está diante de um pedido de reembolso, não de um cancelamento, e o relógio de 12 horas já começou.
• Responda a todo CONSUMPTION_REQUEST que você puder. O RefundHalt envia à Apple dados de consumo precisos dentro da janela de 12 horas e responde à revisão de chargeback do Google Play em até 24 horas, porque esses são os dois únicos momentos em que alguma das lojas pede a sua versão.

Vale a pena pedir acesso à Apple?

Se você vende assinaturas com renovação automática e já trata as App Store Server Notifications V2, provavelmente sim. A tela de cancelamento é o último lugar onde você alcança um assinante antes de ele ir embora, e uma troca de plano custa menos do que perdê-lo de vez. Só reserve orçamento para um endpoint que responda a cada visualização de página de assinatura, e mantenha suas defesas contra reembolso onde os reembolsos de fato acontecem.