Skip to main content
As assinaturas cobram o cartão do cliente automaticamente, em intervalos regulares, sem que ele precise voltar ao seu site a cada ciclo. Servem para planos mensais de software, clubes de assinatura, mensalidades de cursos, academias e qualquer serviço com cobrança recorrente.
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.
Assinaturas e cadastro de cartão não têm modo de teste. Mesmo com a chave de teste (sk_test_), as cobranças da assinatura são reais, inclusive a validação de R$ 1,00 do trial grátis. O cadastro do cartão (POST /v1/cards) também é real, mas não cobra nada. O cofre é o mesmo para teste e produção: um cartão salvo na homologação funciona com a chave de produção. Para homologar, use um cartão real com valor baixo e cancele a assinatura no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. Veja o roteiro de homologação.

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.
Envie customerId ou customer, nunca os dois. Da mesma forma, envie cardTokenId ou paymentMethod. Quando o cartão vai em paymentMethod, o cliente precisa ter e-mail e CPF ou CNPJ; com o objeto customer, envie document. Se já existir um cliente com o mesmo e-mail, vale o documento desse cadastro.
cURL
O cartão precisa estar 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

Para o desenvolvedor: guarde o firstCharge.chargeId. A consulta da assinatura não devolve o id da cobrança: o charges[].id de lá é o registro da assinatura.

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

Com a primeira cobrança em análise, criar uma segunda assinatura para “tentar de novo” pode resultar em duas assinaturas cobrando o mesmo cliente se a análise aprovar a primeira. Aguarde o webhook.

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.
Os detalhes de status, retentativa, atualização e cancelamento estão em Ciclo de vida da assinatura.

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

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.
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.
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.
A documentação descreve assinaturas apenas com cartão de crédito.
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.