Central de ajuda
Produtor

Como funcionam Assinaturas via API

Atualizado em 31 de julho de 2026

Perfil: Produtor
​Área: API do Produtor
​Quem executa: Produtor

A API de Assinaturas permite criar cobranças recorrentes automáticas utilizando cartão de crédito ou pix.

Diferente de uma venda comum, a assinatura cria um vínculo recorrente entre o cliente e o produto, permitindo novas cobranças automáticas conforme a periodicidade configurada.

Esse fluxo é ideal para:

  • Áreas de membros

  • SaaS

  • Clubes de assinatura

  • Assinaturas mensais/anuidade

  • Cobranças recorrentes de serviços

Como funciona o fluxo de assinatura

O processo de assinatura via API acontece em duas partes:

  1. Criação da assinatura

  2. Acompanhamento dos eventos via webhook

A assinatura não deve ser controlada apenas pela resposta da API, pois os pagamentos recorrentes futuros serão informados por webhooks.

Etapa 1: Criando a assinatura

A criação é feita através da rota de assinatura por cartão.

No momento da criação, a API:

  • Valida os dados do cliente

  • Tokeniza/processa o cartão

  • Cria a assinatura recorrente

  • Realiza a primeira cobrança (quando aplicável)

Se tudo ocorrer corretamente, a assinatura passa a existir no gateway.

O que a assinatura controla

Uma assinatura normalmente possui:

  • Produto vinculado

  • Oferta recorrente

  • Periodicidade da cobrança

  • Valor recorrente

  • Cliente assinante

  • Forma de pagamento

Após criada, as próximas cobranças passam a acontecer automaticamente conforme o ciclo configurado.

Exemplo:

  • Mensal → cobrança todo mês

  • Anual → cobrança a cada ano

A resposta da API não é suficiente

Esse é um dos pontos mais importantes da integração.

Ao criar uma assinatura, você não deve confiar apenas no retorno imediato da API para liberar acesso.

O correto é utilizar os webhooks de pagamento.

Por quê?

Porque:

  • O pagamento pode ser aprovado depois

  • Pode entrar em análise

  • Pode falhar

  • Pode ser recusado

  • Pode sofrer chargeback ou cancelamento futuramente

A fonte de verdade do status da assinatura é o webhook.

Etapa 2: Recebendo eventos via Webhook

Após criar a assinatura, o gateway enviará eventos automaticamente para sua URL de webhook.

Os webhooks devem ser utilizados para:

  • Liberar acesso ao produto

  • Bloquear acesso por inadimplência

  • Renovar acesso após recorrência paga

  • Cancelar benefícios quando necessário

Principais eventos do fluxo de assinatura

Embora a assinatura seja recorrente, o comportamento operacional funciona como uma sequência de pagamentos.

Você deve acompanhar especialmente mudanças de status como:

TRANSACTION_CREATED

Indica que a cobrança foi criada, mas ainda aguarda confirmação do pagamento.

Exemplo:

  • Cartão em processamento

  • Tentativa pendente

TRANSACTION_PAID

Indica que a cobrança foi aprovada.

Esse normalmente é o momento correto para:

  • Liberar acesso

  • Renovar assinatura

  • Atualizar permissões do usuário

TRANSACTION_CANCELED

Indica falha na cobrança recorrente.

Exemplo:

  • Cartão recusado

  • Saldo insuficiente

  • Cartão expirado

Nesse caso, normalmente o sistema do integrador deve:

  • Notificar o cliente

  • Suspender benefícios após política interna

TRANSACTION_REFUNDED

Caso uma cobrança seja estornada.

TRANSACTION_CHARGED_BACK

Caso exista contestação bancária da cobrança.

Exemplo de fluxo completo

Mês 1

Cliente cria assinatura:

  • API cria assinatura

  • Webhook TRANSACTION_COMPLETED

  • Cliente recebe acesso

Mês 2

Cobrança automática:

  • Gateway tenta cobrar cartão

  • Webhook TRANSACTION_COMPLETED

  • Assinatura continua ativa

Mês 3

Cartão falha:

  • Gateway tenta cobrança

  • Webhook não é enviado

  • Sistema pode suspender acesso

Mês 4

Cliente atualiza cartão:

  • Nova cobrança aprovada

  • Webhook TRANSACTION_COMPLETED

  • Acesso restaurado

Boa prática recomendada

Nunca baseie o status da assinatura apenas no banco do seu sistema.

Sempre sincronize o estado usando os webhooks do gateway.

Modelo recomendado:

Webhook TRANSACTION_COMPLETED → ativa assinatura  
Webhook não enviado → marca inadimplente  
Webhook TRANSACTION_REFUNDED/TRANSACTION_CHARGED_BACK → suspende acesso

Isso reduz inconsistências e evita liberações indevidas.

Resumo

O fluxo correto de assinatura via API é:

  1. Criar a assinatura pela API

  2. Receber eventos no webhook

  3. Atualizar acesso do cliente com base no status recebido

A criação da assinatura inicia o processo, mas o webhook é o mecanismo que mantém o ciclo recorrente sincronizado ao longo do tempo.

Em integrações de assinatura, o webhook é obrigatório.