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
| Entidade | Descrição | Onde 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"]- Criar Plano: Cadastre o plano no catálogo da loja especificando o valor (
Amount), moeda (Currency), periodicidade (IntervalUniteIntervalCount) e modalidade (PREPAIDouPOSTPAID). Guarde oidretornado. - Criar Cliente: Cadastre o comprador pagador informando dados cadastrais, documento (CPF ou CNPJ) e endereço. Guarde o
idretornado. - Vincular Cartão: Tokenize e salve o cartão no cofre do cliente. Você pode marcá-lo como padrão (
IsDefault: true). - Criar Assinatura: Informe o
PaymentCustomerIde oRecurrencePlanId. O sistema dispara a cobrança imediata do primeiro ciclo e agenda os ciclos futuros. - 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"]- Criar Sessão de Checkout: Sua plataforma envia o
planId(e opcionalmente umcustomerIdpré-existente) e recebe a URL pública de pagamento (checkoutUrl). - Cliente Acessa o Link: O navegador do cliente abre a página de checkout.
- Consultar Sessão: A interface de checkout consulta os dados do plano, valor e periodicidade sem exigir autenticação (
[AllowAnonymous]). - 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.
