SopagueDocs
v3

Visão Geral de Recorrência

A API de Recorrência (WebPayments) permite gerenciar cobranças periódicas automatizadas, planos flexíveis, cadastro de clientes pagadores, tokenização segura de cartões em cofre e sessões de checkout prontas para integração.


Entidades Principais

EntidadeDescriçãoOnde Implementar
Plano (Plan)Regras de cobrança (valor, periodicidade, modalidade pré ou pós-paga, carência e tentativas).Criar Plano · Listar Planos
Cliente (Customer)Pagador cadastrado com dados fiscais e endereço. Permite vincular múltiplos cartões.Criar Cliente · Consultar Cliente
Meio de Pagamento (Payment Method)Cartão de crédito tokenizado com segurança no cofre com criptografia AES-256.Vincular Meio de Pagamento · Listar Meios
Assinatura (Subscription)Contrato ativo que vincula um cliente a um plano com cobrança automática via motor diário.Criar Assinatura · Consultar Assinatura
Fatura (Billing)Registro financeiro de cada ciclo gerado para a assinatura, com histórico de tentativas.Listar Faturas do Cliente
Sessão de Checkout (Checkout Session)Link externo e seguro para o cliente final aderir a um plano e cadastrar o cartão diretamente.Criar Sessão de Checkout · Consultar

Fluxos de Integração

1. Fluxo Direto via API (Transparente)

Recomendado quando a sua aplicação coleta os dados do cliente e do cartão diretamente no seu aplicativo ou plataforma web:

flowchart TD
    A["1. Criar Plano (POST /v2/recurrences/plans)"] --> B["2. Criar Cliente (POST /v2/payment-customers)"]
    B --> C["3. Vincular Cartão (POST /v2/.../payment-methods)"]
    C --> D["4. Criar Assinatura (POST /v2/recurrences/subscriptions)"]
    D --> E["5. Cobrança do 1º Ciclo Imediata"]
    E --> F["6. Próximos Ciclos Automáticos via Motor Diário"]
  1. Criar Plano: Cadastre o plano no catálogo da loja especificando o valor (Amount), moeda (Currency), periodicidade (IntervalUnit e IntervalCount) e modalidade (PREPAID ou POSTPAID). Guarde o id retornado.
  2. Criar Cliente: Cadastre o comprador pagador informando dados cadastrais, documento (CPF ou CNPJ) e endereço. Guarde o id retornado.
  3. Vincular Cartão: Tokenize e salve o cartão no cofre do cliente. Você pode marcá-lo como padrão (IsDefault: true).
  4. Criar Assinatura: Informe o PaymentCustomerId e o RecurrencePlanId. O sistema dispara a cobrança imediata do primeiro ciclo e agenda os ciclos futuros.
  5. Acompanhar Faturas: Consulte a qualquer momento o histórico consolidado de faturas geradas, datas de vencimento e comprovantes das transações.

2. Fluxo via Sessão de Checkout (Link de Pagamento)

Recomendado quando você deseja compartilhar um link seguro para o próprio cliente final escolher o método e inserir os dados do cartão em uma tela hospedada:

flowchart LR
    A["Criar Sessão"] --> B["Enviar Link ao Cliente"]
    B --> C["Consultar Sessão (Público)"]
    C --> D["Pagar Sessão (Público)"]
    D --> E["Assinatura e 1º Pagamento Concluídos"]
  1. Criar Sessão de Checkout: Sua plataforma envia o planId (e opcionalmente um customerId pré-existente) e recebe a URL pública de pagamento (checkoutUrl).
  2. Cliente Acessa o Link: O navegador do cliente abre a página de checkout.
  3. Consultar Sessão: A interface de checkout consulta os dados do plano, valor e periodicidade sem exigir autenticação ([AllowAnonymous]).
  4. Pagar Sessão: O cliente preenche os dados do cartão e confirma. A API tokeniza o cartão no cofre, cadastra o cliente (se novo), ativa a assinatura e processa o primeiro pagamento.

Autenticação e Cabeçalhos

Todas as rotas privadas da API de Recorrência exigem autenticação via Bearer Token JWT obtido no endpoint de Autenticação (POST /api/auth/token).

Authorization: Bearer <seu_token_jwt>
Content-Type: application/json
Idempotency-Key: <uuid_ou_string>

O cabeçalho Idempotency-Key é recomendado em todas as operações de criação e atualização para evitar cobranças ou cadastros duplicados em caso de falha de conexão.