Como cobrar assinatura no seu app sem escrever webhook

Cobrar assinatura no app parece simples até aparecer a parte que ninguém mostra: o cliente paga no provedor, mas o seu sistema precisa saber disso para liberar a tela certa. A cobrança em si é a parte fácil; o difícil é manter o que o usuário pagou e o que o app mostra sempre iguais.

O que você precisa montar

Uma cobrança recorrente tem três peças. O gateway é a credencial do provedor de pagamento dentro do seu projeto. O plano é o nome, o preço em centavos, a moeda e o ciclo mensal ou anual. A assinatura é o vínculo entre um usuário seu e um plano, com o status que o provedor informa.

Um detalhe de implementação que muda o resultado: o preço é sempre em centavos. 2999 vira 29,99. O painel faz essa conversão para você, mas a API não.

Como o acesso chega ao app

O app não consulta o provedor de pagamento. Ele consulta o Payments, que já traduziu o status da cobrança em permissão. No React, o componente FeatureControl esconde o que o plano do usuário não inclui, e o hook useHasFeature devolve um valor booleano para decisões mais finas.

Essa leitura depende de um identificador: o userId que o seu sistema usa no próprio banco, passado ao PaymentsProvider. É por ele que as assinaturas são encontradas. Por isso ele precisa ser estável; trocar o identificador no meio do caminho faz a assinatura do cliente parecer inexistente.

Quando o webhook importa

Mesmo sem você escrever o endpoint, o provedor precisa avisar o Payments quando um pagamento passa ou falha. Sem esse aviso, a cobrança acontece e o acesso continua fechado. O painel mostra a URL do webhook de cada gateway e tem um botão de teste de conexão, que confirma se a chave responde e em que ambiente.

O teste de conexão serve para outra coisa também: chave de teste conecta e responde com sucesso, mas nenhuma cobrança é real. Confira o ambiente antes de publicar.

O que o Payments não faz

Vale deixar claro o que fica de fora:

• A assinatura recorrente passa só pela Stripe.

• Não há métricas de receita, MRR ou churn. A API devolve a contagem de planos e a lista de assinaturas.

• Não há cupom, desconto ou trial configurável por aqui; isso é do próprio provedor.

• Faturas e recibos ficam no painel do provedor, acessíveis pelo PortalButton.

Se o seu modelo depende de algum desses itens, o Payments ainda não atende esse caso.

Para o agente de IA

Quem opera a cobrança por um agente conecta o servidor MCP e começa por payments_get_project, que devolve os ids dos gateways e o modo de teste ou produção. Criar plano e gerar link de cobrança estão disponíveis; apagar plano, cancelar assinatura e ler credencial de gateway não estão, de propósito.

Perguntas frequentes

Preciso escrever webhook para a assinatura funcionar?

Você não escreve o endpoint. O Payments recebe os eventos de pagamento do provedor e atualiza a permissão. Para assinatura, a cobrança recorrente passa só pela Stripe. Basta cadastrar a URL que o painel mostra no provedor, ou usar a configuração automática da Stripe.

Posso ter planos em dois gateways diferentes?

Pode. Um projeto guarda vários gateways, por exemplo produção e sandbox. Cada plano pertence a um gateway, e o gatewayId no Provider escolhe qual tabela de preços a página mostra.

O que acontece quando o cliente cancela?

O status da assinatura muda quando o provedor avisa o cancelamento, e a permissão deixa de valer. O cliente pode gerenciar cartão, faturas e cancelamento pelo portal do provedor.

Para continuar lendo

• Liberar e bloquear partes do app pelo plano do usuário

• Login sem senha com código no e-mail: como funciona e quando usar

• E-mail transacional pelo seu domínio: verificação, eventos e supressão

Conhecer o Payments

Cobrança recorrente e permissão por funcionalidade num lugar só, com a Stripe por baixo da assinatura.

Conhecer o Payments.

Fontes

• Referência do Payments para pessoas e agentes (llms.txt)

• Página do Payments