Pix Automático (Assinaturas)

O que é

O Pix Automático é o produto de recorrência do arranjo Pix (Banco Central): ideal para assinaturas, mensalidades e planos. Diferente de gerar um QR Code novo a cada mês, o pagador autoriza a recorrência uma única vez e, a partir daí, o débito acontece automaticamente na conta dele a cada ciclo — sem ação do pagador e sem ação sua.

Na prática, você cria a assinatura via API (POST /v1/recurrences), exibe o QR Code retornado e passa a ouvir os webhooks. Todo o agendamento e a liquidação dos ciclos são feitos pela plataforma.

Como funciona (Jornada 3: QR único = 1º pagamento + adesão)

Usamos a Jornada 3 do Pix Automático: o QR Code retornado na criação é um QR composto que resolve tudo em um único ato do pagador.

1. Crie a assinatura — envie valor, periodicidade, data de início (mínimo hoje + 1 período da periodicidade, pois a cobrança de ativação já cobre o 1º período) e os dados do pagador para POST /v1/recurrences.
2. Exiba o QR Code — o pagador escaneia no app do banco e, no mesmo ato, paga a primeira cobrança imediata (firstCharge) e autoriza a recorrência.
3. Aprovação — você recebe o webhook recurrence.approved (e o charge.paid da primeira cobrança).
4. Ciclos automáticos — a plataforma agenda e cria a cobrança de cada ciclo (valor fixo) na periodicidade contratada. Você não precisa criar cobranças.
5. Acompanhe pelos webhooks — recurrence.charge.created, recurrence.charge.paid e recurrence.charge.failed informam o andamento de cada ciclo.

POST /api/v1/recurrences
{
  "amount": 49.90,
  "periodicity": "MONTHLY",
  "startDate": "2026-08-10",
  "retryPolicy": "RETRY_3R_7D",
  "customerName": "João da Silva",
  "customerCpf": "12345678901",
  "description": "Plano Ouro",
  "externalReference": "ASSINATURA-001",
  "split": [
    { "subAccountId": "a1b2c3d4-...", "type": "PERCENT", "value": 10 }
  ]
}

Ciclo de vida

A assinatura nasce em PENDING_APPROVAL e evolui conforme a ação do pagador; cada ciclo de cobrança tem o próprio ciclo de vida, do agendamento à liquidação:

Assinatura:
  PENDING_APPROVAL ──► APPROVED ──► CANCELLED
        │                            (integrador, pagador ou PSP)
        ├──► REJECTED  (pagador/banco recusou)
        └──► EXPIRED   (QR de adesão expirou)

Ciclo de cobrança:
  SCHEDULED ──► CREATED ──► ACTIVE ──► PAID
                                 │
                                 ├──► FAILED     (após esgotar retentativas)
                                 └──► CANCELLED  (assinatura cancelada)

• Assinatura: PENDING_APPROVAL → APPROVED | REJECTED | EXPIRED. Uma assinatura APPROVED pode virar CANCELLED por você (via DELETE /v1/recurrences/:id), pelo pagador no app do banco ou pelo PSP.
• Ciclo: SCHEDULED → CREATED → ACTIVE → PAID | FAILED | CANCELLED. Ao cancelar a assinatura, os ciclos agendados que ainda não foram liquidados são cancelados; ciclos pagos não são afetados.

Retentativas

Se a liquidação de um ciclo falhar (ex: saldo insuficiente do pagador), o comportamento depende da retryPolicy definida na criação:

Em ambos os casos, o desfecho do ciclo chega via webhook (recurrence.charge.paid ou recurrence.charge.failed) — trate a falha no seu sistema (ex: suspender o acesso ao plano e oferecer outro meio de pagamento).

Taxas por ciclo

Cada ciclo liquidado é uma transação PIX normal na sua conta: a taxa PIX vigente do seu plano é aplicada por ciclo e o netAmount é creditado no seu saldo. Não há taxa adicional pela assinatura em si — você paga apenas pelas cobranças efetivamente liquidadas.

Split por ciclo

O campo opcional split enviado na criação da assinatura é replicado automaticamente em cada ciclo: a divisão incide sobre o valor líquido de cada cobrança liquidada, com as mesmas regras do Split de Pagamentos (subcontas aprovadas, PERCENT/FIXED, limites de 20 subcontas e 100%).

Webhooks

Os eventos recurrence.* usam o mesmo mecanismo (endpoints cadastrados + assinatura HMAC) dos eventos atuais:

• recurrence.approved / recurrence.rejected / recurrence.expired / recurrence.cancelled — status da assinatura
• recurrence.charge.created / recurrence.charge.paid / recurrence.charge.failed — andamento de cada ciclo

{
  "event": "recurrence.charge.paid",
  "recurrenceId": "a1b2c3d4-...",
  "idRec": "RR1234567820260810abcdefghijk",
  "status": "APPROVED",
  "amount": "49.90",
  "periodicity": "MONTHLY",
  "externalReference": "ASSINATURA-001",
  "customer": { "name": "João da Silva", "cpf": "12345678901" },
  "charge": {
    "chargeId": "b2c3d4e5-...",
    "transactionId": "c3d4e5f6-...",
    "externalId": "txid_abc123xyz",
    "cycle": 2,
    "dueDate": "2026-09-10",
    "amount": "49.90",
    "endToEndId": "E12345678202609101005abc123xyz456",
    "paidAt": "2026-09-10T10:05:23.000Z"
  }
}