Um usuário abriu o miniprograma numa terça e a assinatura tinha sumido. Nosso backend dizia que havia renovado três dias antes, que o pagamento tinha liquidado e que o callback assinado estava lá, parado na fila. Nada disso tinha acontecido. A autorização de débito automático do anfitrião tinha vencido em silêncio, a cobrança nunca chegou ao trilho de pagamentos e o único aviso de cobrança que podíamos enviar tinha sido desligado por uma mudança de regra que ninguém nos contou. A flag de «ativa» no nosso servidor era uma história que a gente tinha contado pra nós mesmos.
Olha, aqui está o ponto: dentro de um miniprograma, renovar não é uma data no seu banco. É uma negociação entre o seu servidor, a autorização de cobrança do anfitrião, as regras de mensagem dele e um sistema de contas que não é seu. Trate isso como um booleano no armazenamento local e você vai continuar entregando o bug acima, release após release.
Quem segura o estado de verdade
O anfitrião segura o mandato. Seu servidor segura o livro de direitos. O cliente não segura nada confiável, porque é exatamente ali que o usuário limpa os dados, troca de celular ou entra por outra super app. Depois que você aceita essa divisão, quase todo incidente de renovação deixa de ser mistério.
| Etapa | Quem segura o estado | O que as regras do anfitrião mudam | O acidente comum |
|---|---|---|---|
| Autorização de débito | O trilho de pagamentos do anfitrião | Mandatos vencem, escopos mudam, reautorizar é um fluxo do anfitrião | Você marca «renovada» no local e o dinheiro nunca saiu |
| Tentativa de cobrança | Seu servidor, como tarefa idempotente | Timings de callback e janelas de retry mudam por anfitrião | Um webhook reenviado sem chave de idempotência cobra duas vezes |
| Período de carência | Seu livro de direitos | O anfitrião pode cortar o acesso antes da sua carência acabar | Usuário bloqueado enquanto a tela ainda diz ativa |
| Aviso de falha | O canal de mensagens do anfitrião | IDs de template, horários silenciosos, opt-out | O aviso nunca chega e o churn parece bug aleatório |
| Sincronia de direitos | Seu servidor, conciliado entre anfitriões | A mesma pessoa, IDs de conta diferentes em cada super app | Pagou num e ficou de fora no outro |
| Reembolso | Anfitrião mais seu livro | Janelas de reembolso, regras de período parcial | Acesso revogado, mas o livro ainda diz pago |
Repare quantas vezes a última coluna diz «a gente acreditou nos próprios dados». É esse o padrão. Um estado de renovação que só existe no frontend é um cache sem fonte de verdade, e cache fica velho do jeito mais caro possível: o usuário vê um paywall que já pagou pra tirar da frente.
O que ninguém bota no slide
Não vamos fingir que o anfitrião é um cano neutro. Tem a comissão, e o que pesa mais, tem regras que se mexem. Um template de mensagem em que você apoiava a cobrança falha pode ser aposentado; um mandato que funcionou dezoito meses pode começar a exigir que o usuário vincule o cartão de novo; uma revisão de categoria pode mudar como o seu setor pode cobrar. Você constrói em cima do contrato de outro, e esse contrato tem uma cláusula de alteração na qual você não vota.
E tem o custo de fazer direito. Tarefas de conciliação, chave de idempotência em cada cobrança, um livro que guarde início e fim de período em vez de um único campo is_active, e uma política de retry que saiba diferenciar «cartão recusado, tenta amanhã» de «autorização perdida, pede pro usuário refazer». É engenharia de verdade, e pra um time pequeno dá mais trabalho que a funcionalidade que precisava da assinatura. Já deu vontade de pular. Toda vez que pulamos, voltou em ticket de suporte.
Direitos entre plataformas são a outra bagunça honesta. Se o mesmo produto roda em dois anfitriões, você tem dois sistemas de contas, dois trilhos de pagamento e dois conjuntos de callback, e uma pessoa que espera que a assinatura vá junto com ela. Mapear essas identidades sem guardar mais dados pessoais do que precisa é, por si só, um pequeno projeto de privacidade. E reembolso não respeita a sua arquitetura: o anfitrião pode estornar numa linha do tempo que seu livro não modelou, então «pago» e «com direito» precisam ser campos separados, que podem discordar por alguns dias sem quebrar nada.
A regulação acrescenta a última volta. Divulgação de renovação automática, caminho de cancelamento e regras de opção negativa variam por mercado, e o checkout do anfitrião não te deixa conforme por mágica. A gente prefere ter esse texto e esse fluxo na mão a presumir que a plataforma cobriu.
Conciliar, não desenhar
Comece assumindo que todo callback do anfitrião é pista, não veredito. Mantenha seu próprio livro de direitos com início e fim de período, anfitrião de origem e a cobrança que gerou aquilo; concilie com o anfitrião por agendamento, não só quando chega um webhook. Torne cada cobrança idempotente. Dê ao período de carência um dono de verdade no código, em vez de um número mágico na interface, e garanta que uma falha de renovação tenha um caminho de aviso que não dependa de um template que você não controla.
O teste prático é chato e vale a pena: revogue um mandato numa conta de teste, corte o callback no meio e veja se o usuário ainda recebe aquilo pelo que pagou. Se a resposta depende do que o cliente desenhou por último, você ainda não tem renovação — tem um estado de carregamento com uma etiqueta que diz «assinatura».
Fontes
- Google Play — Faturamento — como um trilho de pagamentos do anfitrião lida com assinaturas, renovações e carência.
- Apple — Documentação do StoreKit — o modelo de referência para assinaturas autorrenováveis e estado no servidor.
- Stripe — Documentação de Billing — padrões de idempotência, retry e conciliação que valem copiar mesmo sem usar Stripe.
- FTC — Orientações para empresas — por que divulgação de renovação e cancelamento são questão de compliance, não só de UX.
- WeChat — Documentação aberta — onde ficam de fato a autorização de cobrança e as regras de mensagem de template.