Criar recorrência de Pix Automático

Resposta rápida: Chame POST /rec com vínculo, calendário, valor e política de retentativa; guarde o idRec da resposta; a rec nasce CRIADA e só autoriza cobrança quando o pagador aprovar e ela virar APROVADA.

Pré-requisitos

• Token + mTLS funcionando
• Conceito de Pix Automático — em especial a escolha de jornada
• Escopos rec.write e rec.read na credencial (referência)

Decisões antes do primeiro POST

1. Qual conta recebe. O mandato fica amarrado à conta recebedora; migrar depois obriga cada pagador a autorizar de novo.
2. Qual jornada. A 1 aponta ativacao.dadosJornada.txid para uma cobrança que o pagador já vai pagar. A 2 usa payload próprio da recorrência, criado em /locrec. As 3 e 4 compõem o QR da recorrência com uma cobrança imediata ou com vencimento — e essa escolha se faz na hora de ler o QR, não de criar a recorrência.
3. Retentativa. NAO_PERMITE ou PERMITE_3R_7D — decisão de negócio, e ela fica gravada no mandato.
4. Periodicidade e janela. dataInicial, dataFinal e periodicidade definem os ciclos que você poderá cobrar.

Passo a passo

1. Obtenha o token (02).
2. POST /rec com o corpo do snippet. A resposta traz o idRec — persista junto do seu assinante, é a chave de tudo depois.
3. Leve o pagador à autorização, conforme a jornada escolhida.
4. Leia a recorrência para obter o BR Code: GET /rec/{idRec} devolve dadosQR quando as locations da jornada estão preenchidas. Acrescente ?txid={txid} para compor com uma cobrança (jornadas 3 e 4). A criação não devolve QR — só o idRec.
5. Acompanhe o status: por GET /rec/{idRec} ou, melhor, pelo webhook de recorrência.
6. Só quando o status for APROVADA, comece a criar as cobranças do ciclo.

Enquanto a rec estiver CRIADA, alguns campos ainda podem ser revisados por PATCH /rec/{idRec} — entre eles loc, calendario.dataInicial e vinculo.devedor.nome. Depois de REJEITADA ou CANCELADA, não.

Código

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

# source: snippets/curl/create-rec.sh
curl -sS -X POST '{{MODOBANK_API_BASE}}/rec' \
  --cert '{{PATH_TO_CERT}}' \
  --key '{{PATH_TO_KEY}}' \
  --cacert '{{PATH_TO_CA}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "vinculo": {
      "contrato": "63100862",
      "devedor": { "cpf": "45164632481", "nome": "Fulano de Tal" },
      "objeto": "Assinatura mensal do plano Solo"
    },
    "calendario": {
      "dataInicial": "2026-10-01",
      "dataFinal": "2027-10-01",
      "periodicidade": "MENSAL"
    },
    "valor": { "valorRec": "49.90" },
    "politicaRetentativa": "NAO_PERMITE",
    "ativacao": { "dadosJornada": { "txid": "{{TXID}}" } }
  }'

As variantes Node, Python e PHP seguem a mesma forma HTTP dos snippets de token e de cob — troque método, path e corpo; cert, key, CA e Bearer são idênticos.

Solicitação de confirmação (solicrec)

Quando o fluxo pede que o PSP do pagador apresente a autorização a ele, crie uma solicitação com POST /solicrec, informando o idRec e o destinatário (agência, conta, CPF/CNPJ e ispbParticipante). Ela pode ser consultada e revisada por idSolicRec, e só é cancelável enquanto estiver CRIADA, ENVIADA ou RECEBIDA.

Se der errado

Sintoma	Causa	Ação
403 em /rec com token válido	Credencial sem rec.write	Pedir o escopo ao banco — escopo não se manda no token
400 citando rec.dadosJornada.txid	txid de outro recebedor, ou cobrança inexistente	Usar cobrança da própria conta
Status parado em CRIADA por horas	Pagador não autorizou	É o estado normal da espera; não recriar a rec
dadosQR ausente na leitura	location da jornada não preenchida	Criar a location (/locrec) e referenciá-la em loc; nas jornadas 3 e 4, a cobrança também precisa da dela
REJEITADA	Pagador recusou	Não promova o assinante; ofereça outro meio
Cobrança recusada depois de autorizar	cobr sem idRec correto, ou fora da janela do calendário	Conferir idRec e dataDeVencimento

Checklist

• Conta recebedora decidida antes do primeiro mandato
• idRec persistido junto do assinante
• Jornada de autorização implementada
• BR Code lido do GET /rec/{idRec}, não esperado da criação
• Transição para APROVADA observada por webhook
• Nenhuma cobr criada antes de APROVADA

Próximo passo

→ 08 — Cobrar uma recorrência

FAQ

P: Posso cobrar assim que criar a rec?

R: Não. CRIADA é só o pedido; sem APROVADA não há mandato.

P: Quem cancela a recorrência?

R: O pagador, no banco dele. Você recebe o evento CANCELADA — não o provoca.