Cobrar uma recorrência autorizada

Resposta rápida: Para cada ciclo, envie PUT /cobr/{txid} com o idRec, a data de vencimento e o valor; o banco do pagador debita e você acompanha ATIVA → CONCLUÍDA pelo webhook, tratando falha com retentativa quando a recorrência permitir.

Pré-requisitos

• Uma recorrência APROVADA e seu idRec (07)
• Escopos cobr.write e cobr.read

Passo a passo

1. Gere um txid para o ciclo. Ele é seu identificador do ciclo, não do mandato — não reutilize o mesmo txid entre meses.
2. PUT /cobr/{txid} com idRec, calendario.dataDeVencimento e valor.original.
3. Use ajusteDiaUtil quando o vencimento puder cair em fim de semana ou feriado.
4. Aguarde ATIVA (aceita e agendada pelo PSP do pagador) e depois CONCLUÍDA (paga) — via webhook.
5. Em falha, se a recorrência foi criada com PERMITE_3R_7D, solicite nova tentativa com POST /cobr/{txid}/retentativa/{data}.

O valor do ciclo não precisa ser igual ao valorRec da recorrência — o valorRec é referência do mandato, e cada cobr carrega o valor efetivo daquele ciclo, dentro das regras do arranjo.

Código

Fonte canônica: snippets/curl/create-cobr.sh.

# source: snippets/curl/create-cobr.sh
curl -sS -X PUT '{{MODOBANK_API_BASE}}/cobr/{{TXID}}' \
  --cert '{{PATH_TO_CERT}}' \
  --key '{{PATH_TO_KEY}}' \
  --cacert '{{PATH_TO_CA}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idRec": "{{IDREC}}",
    "infoAdicional": "Assinatura mensal do plano Solo",
    "calendario": { "dataDeVencimento": "2026-11-01" },
    "valor": { "original": "49.90" },
    "ajusteDiaUtil": true
  }'

Consulta do ciclo: GET /cobr/{txid}. Revisão antes do vencimento: PATCH /cobr/{txid}.

Um ciclo por vez

Não crie duas cobranças vivas para o mesmo ciclo: a API recusa quando já existe uma cobr do mesmo idRec com vencimento no mesmo ciclo e status diferente de REJEITADA ou CANCELADA. Na prática, antes de criar, consulte o que já existe para aquele mês — um retry cego do seu job vira 400.

Se der errado

Sintoma	Causa	Ação
400 citando ciclo duplicado	Já existe cobr viva para o mesmo vencimento	Consultar antes de criar; tratar o job como idempotente
400 no idRec	Recorrência não APROVADA, ou idRec errado	Conferir status da rec
REJEITADA	PSP do pagador recusou (saldo, limite, mandato inválido)	Retentativa se a política permitir; senão, avisar o cliente
CANCELADA pelo pagador	Cancelamento no banco dele	Encerrar o ciclo e o acesso conforme sua regra
Retentativa recusada	Recorrência criada com NAO_PERMITE	A política está no mandato e não muda depois

Checklist

• txid único por ciclo
• Consulta de ciclo existente antes de criar
• ajusteDiaUtil avaliado
• Caminho de retentativa implementado quando a política permite
• Estado do assinante muda só com confirmação, não com o webhook cru

Próximo passo

→ 09 — Webhooks de recorrência

FAQ

P: Preciso criar as cobranças de todos os meses de uma vez?

R: Não. O padrão é um ciclo por vez, criado perto do vencimento por um job seu.

P: O pagador vê algo a cada ciclo?

R: O débito aparece na conta dele. Nova autorização, só se o mandato mudar.