Este guia explica exatamente como cobrar de forma recorrente via Pix Automático, chamada por chamada. Pix Automático é o débito automático nativo do Pix — você cria uma recorrência (acordo entre você e o pagador) e o sistema gera cobranças automaticamente conforme a periodicidade.

Provedor BaaS: Dock. Você não fala com a Dock — só com a API da Autra.

Conceitos fundamentais

Termo	O que é
Recorrência	Acordo entre recebedor e pagador. Define valor, periodicidade, prazo. Pagador autoriza uma vez no app do banco dele.
Cobrança (billing)	Cobrança individual gerada a partir de uma recorrência. Uma recorrência produz N cobranças automaticamente (uma por período).
Billing Engine	Componente interno da Autra que gera as cobranças automaticamente nas datas certas. Você não chama — ele dispara sozinho.
Recebedor	Você, que está cobrando.
Pagador	O cliente, que paga.
Autorização	Ato do pagador no app do banco dele aceitando o débito automático. Sem isso, nenhuma cobrança é processada.

Antes de começar — checklist

Você tem client_id + client_secret da Autra.
Você sabe gerar Bearer JWT via POST /v1/auth/token.
Você sabe CPF ou CNPJ do pagador (cliente que vai autorizar).
Você decidiu a periodicidade (DAILY, WEEKLY, MONTHLY, etc.) e o valor.
(Opcional, recomendado) Você tem endpoint para receber webhooks da Autra.

Resumo dos endpoints

#	O que faz	Endpoint	Quando usar
1	Criar recorrência	`POST /pix/automatic/recurrences`	No momento do checkout/contrato
2	Listar recorrências	`GET /pix/automatic/recurrences`	Dashboard do recebedor
3	Atualizar status	`POST /pix/automatic/recurrences/{id}/refresh`	Forçar pull do status na Dock
4	Cancelar recorrência	`POST /pix/automatic/recurrences/{id}/cancel`	Cliente saiu / contrato encerrou
5	Listar cobranças	`GET /pix/automatic/recurrences/{id}/billings`	Histórico de cobranças daquela recorrência
6	Criar cobrança avulsa	`POST /pix/automatic/billings`	Caso excepcional (Billing Engine cobre o regular)
7	Cancelar cobrança	`DELETE /pix/automatic/billings/{billingId}`	Cancelar uma cobrança específica antes de processar

Prefixo: https://api.autra.io. Headers: Authorization: Bearer <JWT>, Content-Type: application/json.

State machine

Recorrência

PENDING                  (criada — aguardando autorização do pagador)
  │
  ├─► ACCEPTED           (pagador autorizou no app do banco)
  │     │
  │     ├─► ACTIVE       (gerando cobranças)
  │     │     │
  │     │     ├─► CANCELLED_RECEIVER   (você cancelou)
  │     │     ├─► CANCELLED_PAYER      (cliente cancelou no app do banco)
  │     │     └─► EXPIRED              (data de expiração atingida)
  │     │
  │     └─► CANCELLED_*  (cancelada antes de virar ATIVA)
  │
  ├─► REJECTED           (pagador recusou no app do banco)
  └─► EXPIRED            (autorização não aconteceu no prazo)

Cobrança (billing)

PENDING_SEND     (criada pelo Billing Engine, ainda não enviada à Dock)
  │
  ├─► SENT       (enviada à Dock)
  │    │
  │    ├─► ACTIVE       (sendo processada)
  │    │    │
  │    │    ├─► COMPLETED            ✅ pago!
  │    │    ├─► REJECTED             ❌ banco do pagador rejeitou
  │    │    ├─► EXPIRED              ❌ não foi paga até o vencimento
  │    │    ├─► CANCELLED_RECEIVER   (você cancelou)
  │    │    └─► CANCELLED_PAYER      (pagador cancelou)
  │    │
  │    └─► CANCELLED_*  (cancelada antes de virar ACTIVE)
  │
  └─► SEND_FAILED  (erro técnico ao enviar — Billing Engine retenta)

🟦 Caminho feliz — passo a passo

Passo 1: Criar a recorrência

Esta é a chamada principal. Ela registra o acordo entre você (recebedor) e o pagador.

POST /v1/banking/pix/automatic/recurrences
Authorization: Bearer <JWT>
Content-Type: application/json

{
  "amount":        99.90,
  "currency":      "BRL",
  "periodicity":   "MONTHLY",
  "firstDueDate":  "2026-04-01",
  "expirationDate": "2027-04-01",
  "dayAdjustment": "MOVE_FORWARD_NEXT_BUSINESS_DAY",
  "payerName":     "João Silva",
  "payerTaxId":    "12345678901",
  "description":   "Assinatura mensal Autra"
}

Resposta 200:

{
  "recurrenceId":     "0193b5a1-2c9d-7f1a-8b4e-...",
  "status":           "PENDING",
  "authorizationUrl": "https://nubank.com.br/cobrar/..."
}

✅ Guarde o recurrenceId — chave de tudo daqui em diante. ✅ Mostre o authorizationUrl ao pagador (link, QR Code ou botão "Autorizar no app do banco").

Periodicidades suportadas

Valor	Frequência
`DAILY`	Diária
`WEEKLY`	Semanal
`MONTHLY`	Mensal (mais comum)
`BIMONTHLY`	A cada 2 meses
`QUARTERLY`	Trimestral
`BIANNUAL`	Semestral
`ANNUAL`	Anual

Comportamento em dias não úteis (`dayAdjustment`)

Valor	Efeito
`MOVE_FORWARD_NEXT_BUSINESS_DAY`	Adia para o próximo dia útil (recomendado)
`MOVE_BACKWARD_PREVIOUS_BUSINESS_DAY`	Antecipa para o dia útil anterior
`KEEP_DUE_DATE`	Mantém na data, mesmo em fim de semana/feriado

⚠️ Validações:

amount > 0
payerTaxId precisa ser CPF (11 dígitos) ou CNPJ (14 dígitos), só números.
firstDueDate não pode ser passado.
Se expirationDate for fornecido, precisa ser ≥ firstDueDate.

Passo 2: Pagador autoriza no app do banco

Esta etapa não é uma chamada de API. Você apenas espera.

O pagador clica no authorizationUrl, é redirecionado para o app do banco dele (Nubank, Itaú, Bradesco, etc.), confirma o débito automático e pronto.

Quando isso acontece, a Dock dispara o webhook PIX_AUTOMATIC_RECEIVER_RECURRENCE_ACCEPTED (ou APPROVED) e o backend da Autra atualiza o status para ACCEPTED.

⚠️ Sem essa autorização, nenhuma cobrança é processada. A recorrência fica em PENDING até o pagador autorizar (ou rejeitar/expirar).

✅ Recomendado: assine o webhook PIX_AUTOMATIC_RECEIVER_RECURRENCE_ACCEPTED — você é notificado em segundos. ✅ Alternativa (polling): pollar GET /recurrences/{id}/refresh (passo 3) com backoff.

Passo 3: (Opcional) Forçar atualização do status

Use se o status local pode estar desatualizado e você não quer esperar webhook:

POST /v1/banking/pix/automatic/recurrences/{recurrenceId}/refresh
Authorization: Bearer <JWT>

Resposta 200:

{
  "recurrenceId": "0193b5a1-...",
  "status":       "ACCEPTED"
}

✅ Ele consulta a Dock e atualiza o status no banco da Autra. Use moderadamente — não pollar em loop apertado.

Passo 4: Billing Engine começa a gerar cobranças (automático)

Você não chama nada aqui. Quando a recorrência fica ACCEPTED, o Billing Engine da Autra começa a gerar cobranças automaticamente:

Em firstDueDate, gera a 1ª cobrança.
Em firstDueDate + 1 período, gera a 2ª.
E assim por diante até expirationDate (ou cancelamento).

Cada cobrança passa por: PENDING_SEND → SENT → ACTIVE → COMPLETED (ou erro).

Quando o pagador paga, a Dock dispara webhook PIX_AUTOMATIC_RECEIVER_BILLING_COMPLETED e o backend marca a cobrança como COMPLETED. É aqui que o dinheiro caiu na sua conta.

Passo 5: Listar cobranças de uma recorrência

Para o dashboard do cliente recebedor:

GET /v1/banking/pix/automatic/recurrences/{recurrenceId}/billings?limit=50&offset=0
Authorization: Bearer <JWT>

Resposta 200:

{
  "total": 12,
  "items": [
    {
      "id":            "...",
      "recurrenceId":  "...",
      "status":        "COMPLETED",
      "amount":        99.90,
      "currency":      "BRL",
      "dueDate":       "2026-04-01",
      "idTx":          "...",
      "sendAttempts":  1,
      "createdAt":     "2026-03-30T03:00:00Z",
      "updatedAt":     "2026-04-01T10:23:11Z"
    },
    ...
  ]
}

✅ Use isso pra mostrar histórico de pagamentos por cliente.

Operações secundárias

Listar todas as recorrências

GET /v1/banking/pix/automatic/recurrences?limit=50&offset=0
Authorization: Bearer <JWT>

Retorna todas as recorrências do tenant (lista paginada). Use para dashboard geral.

Cancelar uma recorrência

POST /v1/banking/pix/automatic/recurrences/{recurrenceId}/cancel
Authorization: Bearer <JWT>

→ status: CANCELLED_RECEIVER. Nenhuma nova cobrança é gerada. Cobranças pendentes são canceladas.

⚠️ Irreversível. Para reativar, crie uma nova recorrência.

Criar cobrança avulsa (excepcional)

POST /v1/banking/pix/automatic/billings
Authorization: Bearer <JWT>

{
  "recurrenceId":  "0193b5a1-...",
  "dueDate":       "2026-04-15",
  "amount":        49.90,
  "currency":      "BRL",
  "dayAdjustment": "MOVE_FORWARD_NEXT_BUSINESS_DAY"
}

⚠️ Use com cuidado. O Billing Engine já gera as cobranças regulares. Use /billings (POST) só para casos excepcionais (ex.: cobrança extra fora do calendário, ajuste pontual).

⚠️ Pré-condição: recorrência precisa estar em ACCEPTED (ou ACTIVE). Senão recebe 500.

Cancelar uma cobrança específica

DELETE /v1/banking/pix/automatic/billings/{billingId}
Authorization: Bearer <JWT>

→ status da cobrança: CANCELLED_RECEIVER.

⚠️ Só cobranças em status cancelável (PENDING_SEND, SENT, ACTIVE antes de processar) podem ser canceladas. COMPLETED é terminal.

Webhooks (recomendado em produção)

Sem webhooks, você precisa pollar refresh ou listar — caro e lento. Com webhooks, o backend te avisa em segundos.

Endpoint que você expõe: POST <seu-endpoint> com body cifrado em AES-256-GCM (chave compartilhada via Setup).

Eventos de Recorrência

`event_type`	O que significa	O que fazer
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_ACCEPTED`	Pagador autorizou ✅	Atualizar UI: "Autorização recebida"
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_APPROVED`	Banco do pagador aprovou tecnicamente	Apenas registrar
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_REJECTED`	Banco do pagador rejeitou ❌	Notificar que precisa criar nova recorrência
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_CANCELED`	Recorrência foi cancelada	Atualizar UI
`PIX_AUTOMATIC_PAYER_RECURRENCE_CANCELED`	Pagador cancelou no app do banco	Notificar recebedor — o cliente saiu
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_EXPIRED`	Pagador não autorizou no prazo	Criar nova recorrência se ainda quiser cobrar
`PIX_AUTOMATIC_RECEIVER_RECURRENCE_EXPIRED_END_DATE`	`expirationDate` atingida	Renovar contrato com nova recorrência

Eventos de Cobrança (Billing)

`event_type`	O que significa	O que fazer
`PIX_AUTOMATIC_RECEIVER_BILLING_REQUESTED`	Cobrança criada pelo Billing Engine	Apenas registrar
`PIX_AUTOMATIC_RECEIVER_BILLING_ACTIVE`	Cobrança sendo processada	Apenas registrar
`PIX_AUTOMATIC_RECEIVER_BILLING_COMPLETED`	Pago! 🎉	Atualizar saldo, enviar nota fiscal, liberar serviço
`PIX_AUTOMATIC_RECEIVER_BILLING_REJECTED`	Banco rejeitou (sem saldo, etc.)	Notificar cliente, retentar conforme política
`PIX_AUTOMATIC_RECEIVER_BILLING_EXPIRED`	Não pago até o vencimento	Notificar cliente, marcar inadimplência
`PIX_AUTOMATIC_RECEIVER_BILLING_CANCELED_RECEIVER`	Você cancelou	Apenas registrar
`PIX_AUTOMATIC_RECEIVER_BILLING_CANCELED_PAYER`	Pagador cancelou	Apenas registrar

⚠️ A Dock também envia eventos PAYER_* mesmo para o recebedor. O backend da Autra trata os dois (mesmo idTx) — você só precisa lidar com os RECEIVER_* na sua lógica.

Idempotência

Criar recorrência — não tem idempotency-key. Se a chamada falhar e você reenviar, vai criar 2 recorrências. Cuidado.
Refresh — idempotente naturalmente (apenas leitura).
Cancelar — idempotente. Cancelar 2x não muda nada.
Webhooks — backend trata duplicação (mesmo idTx + status já aplicado é no-op).

✅ Recomendação: se o POST /recurrences falhar com timeout/erro de rede, antes de retentar, liste com filtro por payerTaxId + amount + firstDueDate para detectar se já criou.

Erros comuns

HTTP	Quando ocorre	O que fazer
`400`	Parâmetros inválidos (CPF malformado, valor ≤ 0, data passada)	Validar no front antes
`403`	Token inválido / expirado	Renovar JWT via `/auth/token`
`404`	`recurrenceId` ou `billingId` não existe	Verificar IDs
`500`	Erro interno ou na Dock	Retry com backoff (3x, 1s/3s/9s). Se persistir, abrir suporte.

Boas práticas

Cache JWT no backend chamador — não gere token a cada request.
Use webhooks, não polling. Polling deve ser fallback raro.
Mostre o authorizationUrl em destaque — sem autorização do pagador, nada acontece.
Trate EXPIRED da recorrência — clientes que demoram para autorizar viram churn silencioso.
Monitore BILLING_REJECTED — pode indicar saldo insuficiente do cliente, hora de notificar.
Idempotency caseira: liste recorrências por payerTaxId + amount + firstDueDate antes de criar uma nova, para evitar duplicatas em caso de retry de rede.
Não use POST /billings (cobrança avulsa) como atalho — confie no Billing Engine para o calendário regular.

Limitações conhecidas

Idempotency-Key não suportado em POST /recurrences hoje. Mitigue listando antes de retentar.
Edição de valor/periodicidade não é possível após ACCEPTED. Para mudar, cancele e crie nova.
Pagador pode cancelar a qualquer momento no app do banco dele — você é notificado via webhook PAYER_RECURRENCE_CANCELED.
Cobranças com dueDate no passado são rejeitadas pela Dock.

FAQ

Posso editar o valor de uma recorrência ativa? Não. Cancele e crie outra com o novo valor.

O cliente cancelou no app do banco. Posso reativar? Não. Crie uma nova recorrência. O cliente terá que autorizar novamente.

O que acontece se o cliente não tem saldo no dia do débito? A cobrança vai pra REJECTED (ou EXPIRED dependendo do banco). A próxima cobrança do ciclo é gerada normalmente — não há retentativa automática da mesma cobrança.

Posso ter várias recorrências para o mesmo pagador? Sim. Cada payerTaxId pode ter quantas recorrências distintas você quiser (ex.: assinatura básica + addon).

Como sei se o cliente autorizou? Webhook PIX_AUTOMATIC_RECEIVER_RECURRENCE_ACCEPTED ou polling com POST /recurrences/{id}/refresh.

O Billing Engine retenta cobranças que falharam? Não na mesma cobrança. A próxima cobrança do ciclo é gerada normalmente. Para retentar manualmente, use POST /billings (avulsa).

Qual a periodicidade mínima/máxima? Mínima: DAILY. Máxima: ANNUAL. Para fora disso, gerencie manualmente com cobranças avulsas.

Posso cobrar valores variáveis (utilities, telefonia)? Sim. Use POST /billings (avulsa) para cobrança variável e ignore o calendário regular do Billing Engine. Mas o setup recorrente assume valor fixo.

Quanto tempo o pagador tem para autorizar? Configurado pela Dock — geralmente alguns dias. Se não autorizar, a recorrência vai para EXPIRED.

Existe rate limit? Sim. Padrão Autra: 100 req/min por tenant. Pra mais, fale conosco.

Conceitos fundamentais

Antes de começar — checklist

Resumo dos endpoints

State machine

Recorrência

Cobrança (billing)

🟦 Caminho feliz — passo a passo

Passo 1: Criar a recorrência

Periodicidades suportadas

Comportamento em dias não úteis (dayAdjustment)

Passo 2: Pagador autoriza no app do banco

Passo 3: (Opcional) Forçar atualização do status

Passo 4: Billing Engine começa a gerar cobranças (automático)

Passo 5: Listar cobranças de uma recorrência

Operações secundárias

Listar todas as recorrências

Cancelar uma recorrência

Criar cobrança avulsa (excepcional)

Cancelar uma cobrança específica

Webhooks (recomendado em produção)

Eventos de Recorrência

Eventos de Cobrança (Billing)

Idempotência

Erros comuns

Boas práticas

Limitações conhecidas

FAQ

Comportamento em dias não úteis (`dayAdjustment`)