Assinaturas
Referência
Assinaturas automatizam cobranças recorrentes para o mesmo cliente, eliminando a necessidade de criar manualmente uma nova cobrança a cada período. Este guia explica como elas funcionam na ValidaPay, como são criadas e o que a API permite fazer depois da criação.
POST /v1/subscriptions. Uma assinatura nasce quando um checkout com produto recorrente (recurrenceType diferente de ONE_TIME) é pago com sucesso. As rotas em Assinaturas servem para consultar e gerenciar assinaturas já existentes.Quando utilizar
Use assinaturas quando sua integração precisa cobrar o mesmo cliente em intervalos regulares, mantendo histórico de ciclos, planos e pagamentos em um único relacionamento.
- Mensalidades de academias, escolas, clubes e associações
- Planos SaaS com cobrança mensal, trimestral ou anual
- Serviços recorrentes: manutenção, suporte, licenças e memberships
- Marketplaces e plataformas com receita periódica do mesmo cliente
Pré-requisitos
Antes de ter assinaturas ativas na sua integração, certifique-se de:
- Produto cadastrado com preço recorrente (recurrenceType diferente de ONE_TIME)
- Fluxo de checkout implementado (Transparente ou Session)
- Webhooks de assinatura configurados para acompanhar o ciclo de vida
- Token OAuth com escopos subscriptions/read e subscriptions/write para gestão
Principais parâmetros
Alguns campos influenciam diretamente o comportamento da recorrência. A referência completa de cada rota está nas páginas da API; aqui estão os que mais impactam integrações.
| Campo | Impacto na recorrência |
|---|---|
subscriptionId | Identificador usado em todas as rotas de consulta e alteração |
status | Estado atual da assinatura: ACTIVE, PAST_DUE, CANCELED, etc. |
interval / recurrenceType | Periodicidade do plano: MONTHLY, YEARLY e demais tipos recorrentes |
paymentType | Método de cobrança da assinatura: cartão, PIX ou boleto |
nextCycleChargeDate | Data prevista da próxima cobrança recorrente |
nextCycleAmount | Valor estimado do próximo ciclo, já considerando itens ativos |
billingCycles[] | Histórico de ciclos com invoices e charges de cada período |
items[] | Planos e add-ons vinculados: recorrentes (RECURRING) ou avulsos (ONE_TIME) |
Consulte Buscar Assinatura para ver billingCycles, upgrades e priceSchedulePreview no detalhe.
Assinatura recorrente, item avulso e parcelamento
Embora todos envolvam pagamentos ao longo do tempo, os comportamentos são diferentes. Confundir esses modelos é uma das causas mais comuns de integração incorreta.
| Recorrente | ONE_TIME | Parcelamento (cartão) | |
|---|---|---|---|
| O que é | Relacionamento contínuo; novas cobranças surgem a cada ciclo | Item ou produto cobrado uma única vez, sem renovação | Compra parcelada no cartão, com valor total dividido em parcelas fixas |
| Como nasce | Checkout pago com produto recorrente → assinatura criada automaticamente | Add item ONE_TIME em assinatura existente ou produto avulso no checkout | Checkout com parcelamento no cartão, que não gera assinatura recorrente |
| Cobranças futuras | Geradas automaticamente conforme a periodicidade | Nenhuma. Após o pagamento, o item fica como CHARGED | Todas as parcelas criadas na compra; sem novos ciclos automáticos |
| API de assinaturas | Consulta, upgrade, downgrade, cancelamento via /v1/subscriptions | Pode aparecer como item; assinaturas só ONE_TIME são excluídas da listagem | Fora do módulo de assinaturas: trate como cobrança avulsa |
Como uma assinatura é criada
Cadastrar produto
Preço com recurrenceType recorrente (MONTHLY, YEARLY, etc.)
Checkout
Cliente paga via Checkout Transparente ou Session
Pagamento aprovado
Primeira cobrança confirmada (cartão ou webhook)
Assinatura criada
Sistema gera subscriptionId e agenda os ciclos futuros
Fluxo das cobranças recorrentes
Após a criação, a ValidaPay gera novos ciclos automaticamente conforme a periodicidade do preço contratado. Você acompanha o próximo ciclo em nextCycleChargeDate ao consultar a assinatura.
Ciclo anterior encerra ou vence
Conforme nextCycleChargeDate
Nova charge gerada
Automaticamente pela ValidaPay
Cliente paga
Cartão, PIX ou boleto conforme paymentType
Webhook informa
subscription.renewed ou payment.success / payment.failed
Regras importantes
- •Novos ciclos de cobrança são gerados automaticamente conforme a periodicidade do preço contratado.
- •Alterar plano (upgrade/downgrade) impacta cobranças futuras; upgrade pode gerar cobrança de pro rata imediata.
- •Downgrade costuma ser agendado para o próximo ciclo (nextCycleChargeDate), sem cobrança imediata.
- •Cancelar assinatura (DELETE) impede novos ciclos, mas não remove cobranças ou faturas já emitidas.
- •Em PIX e boleto, a confirmação de pagamento chega via webhook: o HTTP 200 não significa pagamento confirmado.
- •Assinaturas cujo intervalo é ONE_TIME são excluídas da listagem GET /v1/subscriptions.
Impactos operacionais
Como novas cobranças são geradas automaticamente ao longo do tempo, integrações que fazem sincronização, conciliação, emissão de NF ou relatórios devem considerar:
- •Novas charges podem surgir sem nova chamada de criação, a cada renovação de ciclo.
- •Integrações de conciliação, ERP e emissão de NF devem escutar webhooks, não apenas polling.
- •Uma assinatura pode acumular várias cobranças ao longo do tempo (ciclos, pro rata, add-ons).
- •Upgrades com PIX/boleto ficam pendentes até payment.success; o plano só troca após confirmação.
Por isso, recomendamos webhooks em vez de polling periódico para acompanhar o ciclo de vida.
Boas práticas
- Cadastre webhooks antes de ir a produção: especialmente subscription.activated e payment.success.
- Não assuma uma única cobrança por assinatura; cada ciclo gera novas charges e invoices.
- Persista subscriptionId e checkoutId logo após o pagamento inicial para consultas futuras.
- Use Calcular Pro Rata para simular upgrade antes de cobrar o cliente.
- Separe a lógica de cartão (confirmação síncrona) de PIX/boleto (confirmação assíncrona).
Gestão no painel ValidaPay
Além da API, o painel oferece a tela de Detalhes da Assinatura: produto, cliente, ciclos, cobranças e faturas em um só lugar. O subscriptionId exibido no rodapé é o mesmo usado nas rotas da API.
Produto e plano
Visualize o produto contratado, se é recorrente ou avulso, o plano ativo e o valor da mensalidade.
Dados do cliente
Consulte nome, documento, e-mail, telefone e endereço de cobrança vinculados à assinatura.
LTV (Lifetime Value)
Acompanhe o total já pago pelo cliente ao longo do relacionamento com sua empresa.
Ciclos de cobrança
Veja a mensalidade, o dia de cobrança, o ciclo atual e o intervalo (mensal, anual, etc.).
Histórico de cobranças
Navegue por cada ciclo com status (pago, pendente), datas de emissão, vencimento e pagamento, incluindo cobranças pró-rata.
Faturas e invoices
Consulte o andamento de cada fatura do ciclo, valores cobrados e situação de emissão por período.
O que a API de assinaturas permite
Consultar e gerenciar assinaturas já existentes: listar, buscar detalhes, upgrade/downgrade, adicionar itens, simular pro rata e cancelar.
| Operação | Descrição |
|---|---|
| Listar Assinaturas | Consultar assinaturas com filtros e paginação. |
| Buscar Assinatura | Detalhes completos: items, billingCycles, upgrades. |
| Calcular Pro Rata | Simular valor de troca de plano (não cobra). |
| Atualizar Item | Upgrade ou downgrade de plano (rota canônica PUT). |
| Atualizar Assinatura (Item) | Upgrade/downgrade via PATCH (alternativo ao PUT). |
| Adicionar Item | Incluir add-ons ou itens ONE_TIME. |
| Cancelar Item | Remover um item mantendo a assinatura ativa. |
| Cancelar Assinatura | Encerrar assinatura e ciclos futuros (DELETE). |
Pagamentos assíncronos (boleto e PIX)
Em upgrade, add item ou renovação com boleto/PIX, a API responde 200 com payment.transactionId (e link/QR quando aplicável). A confirmação efetiva chega via webhook. Não trate o 200 como pagamento confirmado.
No checkout com cartão, o 1º pagamento dispara subscription.activated diretamente, e payment.success não é enviado nesse fluxo.
Status da assinatura
| Status | Significado |
|---|---|
PENDING | Assinatura criada, aguardando o primeiro pagamento. |
AWAITING_PAYMENT | Cobrança emitida (boleto/PIX), aguardando pagamento do cliente. |
ACTIVE | Assinatura ativa com cobranças recorrentes em dia. |
TRIALING | Período de trial em andamento, sem cobrança ainda. |
PAST_DUE | Pagamento do ciclo atual em atraso (cartão). |
PAUSED | Assinatura pausada temporariamente. |
CANCELED | Assinatura cancelada, sem novas cobranças. |
INCOMPLETE | Assinatura incompleta: fluxo de pagamento não finalizado. |