Skip to main content
POST
Esta é a rota do checkout de assinatura. Com ela você liga um cliente a um plano e define o cartão que será cobrado automaticamente a cada ciclo, sem que o cliente precise digitar o CVV de novo. A primeira cobrança (ou a validação do cartão, no trial grátis) acontece na própria chamada, e as renovações seguintes ficam por conta da Finvia.

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário com a permissão criar assinaturas. Nos perfis padrão, são Owner, Manager e Operador. Os perfis Visualizador, Desenvolvedor e Financeiro recebem 403 (veja Permissões por perfil).
  • Tenha um plano ativo (Criar plano, Consultar plano). Plano inexistente ou inativo devolve 404.
  • O cliente precisa ter e-mail e CPF ou CNPJ quando o cartão é cadastrado nesta chamada (cartão em paymentMethod). O tipo do documento é deduzido pela quantidade de dígitos: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento.
  • No fluxo recomendado, registre antes o cartão em Registrar cartão. O cartão precisa pertencer ao mesmo merchant da chave usada. Com cardTokenId, o cartão já está cadastrado e não há nova checagem de documento.
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. Veja como homologar em Assinaturas: visão geral.

O que acontece no checkout

1

Validação do plano

O plano informado em subscriptionPlanId precisa existir e estar ativo.
2

Cliente

Com customerId, o cliente existente é usado. Com o objeto customer, a Finvia localiza o cliente pelo e-mail ou cria um novo. Se o cliente já existe, vale o documento do cadastro, e não o enviado na requisição.
3

Cartão

Com paymentMethod, o cartão é registrado no cofre da Finvia e nasce active. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é 400 e a assinatura não é criada. Com cardTokenId, o cartão já registrado é usado.
4

Validação do trial grátis

Só em plano com trial grátis e sem skipTrial: true: a Finvia cobra R$ 1,00 e estorna em seguida (o estorno é assíncrono). Se essa cobrança for recusada, ficar em análise ou o processador não responder, a resposta é 422 CARD_VALIDATION_FAILED e nada é criado: nem assinatura, nem webhook. Nos demais planos, a própria primeira cobrança valida o cartão.
5

Primeira cobrança

A cobrança acontece na criação da assinatura: sem trial, cobra o valor cheio; com trial pago, cobra o valor do trial; com skipTrial: true, cobra o valor cheio.
6

Assinatura criada

Se a cobrança for aprovada, a assinatura fica active. Se for recusada ou ficar em análise, fica pending_activation. O ciclo fica ancorado na data e hora da contratação (ou no fim do trial, em planos com trial).

Corpo da requisição

Campo obrigatório: subscriptionPlanId. Informe também o cliente (customerId ou customer) e o cartão (cardTokenId ou paymentMethod).
string
required
ID do plano de assinatura. Ex.: 2RhQg9M7ZCg3X3nMb9W2kY9R.
Não há como escolher o dia de cobrança. O ciclo é ancorado na data e hora da contratação, ou no fim do trial. Um campo billingDay enviado é ignorado, sem erro e sem efeito. As regras de renovação estão em Ciclo de vida.
string
ID de um cliente já cadastrado. Use este campo ou o objeto customer, nunca os dois. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
object
Dados do cliente. Use este objeto ou customerId, nunca os dois. A Finvia procura o cliente pelo e-mail e, se não encontrar, cria um novo.
string
ID de um cartão já registrado em Registrar cartão, pela mesma conta. Use este campo ou paymentMethod, nunca os dois. As cobranças da assinatura não pedem CVV. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo.
object
Dados de um cartão novo, que é registrado junto com a assinatura. Use este objeto ou cardTokenId, nunca os dois.
boolean
deprecated
Obsoleto. O campo é aceito, mas não tem efeito: o cartão nasce active, sem transação de teste e sem etapa de ativação. A única validação extra é a de R$ 1,00 do trial grátis, que não depende deste campo.
boolean
Quando true, ignora o trial do plano (se houver) e cobra o valor cheio na criação da assinatura. O padrão é false.
object
Informações suas, em formato livre, guardadas na assinatura. Ex.: {"referralCode": "PROMO2024"}.
Para o negócio: no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R$ 1,00 (a cobrança de validação e o estorno). Avise isso no checkout. Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até 15 minutos, a API reaproveita a validação aprovada e não cobra o R$ 1,00 de novo.

Respostas

string
Identificador único da assinatura. Guarde este valor: ele é usado para consultar, atualizar, cancelar e conciliar com os webhooks (data.id nos eventos subscription.*).
string
Situação da assinatura:Na criação, só esses dois status são possíveis.

Assinatura em pending_activation

A API não tenta de novo a primeira cobrança, e Atualizar assinatura só aceita assinaturas active. A assinatura só sai desse status sozinha em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (firstCharge.pending: true ou trialCharge.pending: true) e a análise aprovou. Aí ela passa a active e o webhook subscription.activated é enviado. Se a análise recusar, chega subscription.payment_failed e a assinatura continua pending_activation. Para tentar de novo (por exemplo, com outro cartão), crie uma nova assinatura por esta rota. A API não reaproveita a pendente: a nova assinatura tem outro id. Cancele a pendente em Cancelar assinatura para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada.
string
ID do cartão registrado usado na assinatura. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo.
string
Início do período de cobrança atual (formato date-time).
string
Fim do período de cobrança atual (formato date-time).
object
Só em plano com trial grátis (sem skipTrial). Resultado da validação de R$ 1,00.
object | null
Resultado da primeira cobrança.
object | null
Resultado da cobrança do trial pago. Traz os mesmos campos de firstCharge, inclusive success, pending e chargeId.

Erros da validação do trial grátis

Os erros 409, 422 e 429 têm o formato { code, message }, sem statusCode. Decida o fluxo pelo code e use a message só para exibir. No 422, o <motivo> é texto livre: pode ser o motivo devolvido pelo processador, pagamento em análise. Use outro cartão., cobrança recusada. ou processador indisponível.. Nesses casos nada é criado: nem assinatura, nem webhook.
Para o negócio: a primeira cobrança acontece na criação da assinatura. Se ela for recusada, a assinatura fica pending_activation, não cobra e não renova: o checkout deve oferecer em seguida outro cartão, criando uma nova assinatura. Depois de ativa, as renovações são feitas por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), com retentativas em caso de recusa. Os detalhes estão em Ciclo de vida.

Exemplos por caso de uso

Cliente e cartão já cadastrados. O cartão foi registrado em POST /v1/cards e nasceu active.

Erros comuns

Veja também

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Planos

Recorrência, trial e status do plano.

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Webhooks de assinatura

subscription.created, subscription.activated e demais eventos.

Registrar cartão

Guarde o cartão no cofre antes de criar a assinatura.

Homologação

Cenários SUB-01 a SUB-06.