Para o negócio: com assinatura, a Finvia cuida da cobrança de cada ciclo e das novas tentativas quando o cartão é recusado, e avisa o seu sistema de cada renovação, falha e cancelamento. O cancelamento em até 7 dias da contratação estorna automaticamente as cobranças pagas (veja Ciclo de vida). A sua equipe define o plano (preço e periodicidade) e a sua plataforma controla o acesso do assinante a partir dos avisos.
Quando usar
Assinatura ou cartão salvo?
As três peças
O cartão, guardado no cofre de cartões, é o meio de pagamento da assinatura.
O desenho abaixo mostra como cliente, plano e cartão se juntam na assinatura e o que acontece a cada ciclo.
Como funciona
O fluxo recomendado é o cards-first: o cartão é registrado antes e a assinatura é criada a partir dele. A sequência abaixo mostra o fluxo cards-first de ponta a ponta, com a diferença entre plano com trial grátis e os demais.1
Crie o cliente
POST /v1/customers com nome, e-mail, CPF ou CNPJ. Veja Clientes.2
Crie o plano
POST /v1/subscription-plans com preço, moeda BRL e recorrência. Normalmente feito uma vez, na configuração do produto. Veja Planos.3
Registre o cartão
POST /v1/cards com os dados do cartão. O cartão já nasce ativo.4
Crie a assinatura com cardTokenId
POST /v1/subscriptions com subscriptionPlanId, customerId e cardTokenId.5
Primeira cobrança
A primeira cobrança é processada imediatamente (ou o trial começa). Se aprovada, a assinatura fica
active.6
Cobranças automáticas
A cada ciclo, a Finvia cobra o cartão e envia os webhooks de renovação ou de falha.
O cartão já nasce ativo ao ser registrado. Não existe transação de teste nem etapa de ativação, e o campo
validateCard é obsoleto e não tem efeito.Formas de criar a assinatura
A criação combina duas escolhas: como informar o cartão e como informar o cliente.- 1. cardTokenId (recomendado)
- 2. Cartão inline
- 3. Cliente e cartão inline
cURL
active e pertencer ao mesmo merchant da chave de API.Campos da criação
Não há como escolher o dia da cobrança: o ciclo é ancorado na data e hora da contratação (ou no fim do trial). Um
billingDay enviado é ignorado, sem erro.Resposta
O que acontece no checkout
O desenho abaixo mostra cada verificação feita na criação da assinatura e o resultado de cada caminho.1
Validação do plano
O plano é validado. Plano inexistente ou inativo gera
404 com Subscription plan not found or inactive.2
Cliente
O cliente é criado ou localizado pelo e-mail. Se ele já existe, vale o documento do cadastro.
3
Cartão
Com
paymentMethod, o cartão é registrado no cofre da Finvia e já nasce ativo. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é 400 com Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador.4
Validação do trial grátis
Em plano com trial grátis (sem
skipTrial), a Finvia cobra R$ 1,00 e estorna em seguida, para validar o cartão. Se a cobrança for recusada, ficar em análise ou o processador não responder, a resposta é 422 CARD_VALIDATION_FAILED e nada é criado. Reenviar a mesma requisição em até 15 minutos reaproveita uma validação aprovada.5
Primeira cobrança
A primeira cobrança é feita imediatamente: o valor do trial pago, ou o valor cheio quando não há trial.
6
Gravação
A assinatura é gravada com status
active se a cobrança for aprovada.Primeira cobrança recusada ou em análise
Ciclo de cobrança
- O ciclo fica ancorado na data e hora da contratação. Em plano com trial, a referência passa a ser o fim do trial, quando a primeira cobrança cheia é feita.
- No mensal, o dia de referência é mantido mesmo em meses mais curtos.
- As renovações são feitas por uma rotina que roda às 6h, 12h e 18h (horário de Brasília). Se a renovação for recusada, há novas tentativas e, no limite delas, a assinatura passa a
expired.
Regras de negócio
Permissões por perfil
A chave de API herda o perfil do usuário que a gerou, e cada rota de planos e assinaturas exige uma permissão. Sem ela, a resposta é403:
Para integrar assinaturas, gere a chave com um usuário Owner ou Manager.
Erros comuns
Perguntas frequentes
Preciso criar o cliente e o cartão antes?
Preciso criar o cliente e o cartão antes?
Não é obrigatório. É possível criar tudo em uma chamada, com o objeto
customer e o paymentMethod. O fluxo cards-first (cliente e cartão antes) é o recomendado porque separa os erros de cadastro dos erros de cobrança.Posso testar assinaturas no sandbox?
Posso testar assinaturas no sandbox?
Não. Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R$ 1,00 do trial grátis. Use um cartão real com valor baixo e cancele no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas.
Se eu aumentar o preço do plano, os assinantes atuais pagam mais?
Se eu aumentar o preço do plano, os assinantes atuais pagam mais?
Não. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só as novas assinaturas usam o novo preço.
Posso oferecer assinatura com Pix?
Posso oferecer assinatura com Pix?
A documentação descreve assinaturas apenas com cartão de crédito.
Como o cliente troca de plano?
Como o cliente troca de plano?
Não existe troca de plano. Cancele a assinatura atual e crie outra no novo plano. A nova começa um ciclo novo, com cobrança imediata.
Como testar
Veja também
Planos
Preço, recorrência, trial e desativação.
Ciclo de vida
Status, retentativa e cancelamento.
Webhooks de assinatura
Eventos de cada etapa.
SaaS e assinaturas
Caso de uso completo.

