Pix Automático (assinaturas)

No Pix Automático, o seu cliente autoriza a assinatura uma vez, no app do banco dele. Depois disso, a cada ciclo (semanal, mensal, trimestral, semestral ou anual) o valor é debitado no vencimento — sem QR novo, sem boleto e sem lembrar de pagar. É o Pix para academias, escolas, planos e serviços por assinatura.

Criar a assinatura

curl -X POST https://api.exemplo.com.br/v1/subscriptions \
  -H "Authorization: Bearer $PIX_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "period": "monthly",
    "start_date": "2026-11-05",
    "description": "Plano Mensal Academia",
    "payer": { "name": "Maria Assinante", "document": "12345678909" },
    "first_payment_amount": "49.90",
    "retry_policy": "three_in_seven_days"
  }'

• amount: valor de cada ciclo; start_date: vencimento do 1º ciclo recorrente (pelo menos daqui a 2 dias).
• payer é obrigatório: a autorização é do CPF/CNPJ do pagador, no banco dele.
• first_payment_amount (opcional): cobra o 1º pagamento na hora, no mesmo QR da adesão — o cliente paga e autoriza numa só leitura. Sem ele, o QR só autoriza a recorrência.
• retry_policy: three_in_seven_days tenta o débito de novo (até 3 vezes em 7 dias) quando não houve saldo.

A resposta traz checkout_url (página de adesão com o QR, pronta para mandar ao cliente) e br_code (Pix Copia e Cola da adesão). Veja todos os campos na referência.

O que acontece depois

Momento	Assinatura	Eventos
Criada	pending	subscription.created
Cliente aprova no app do banco	active	subscription.approved (e charge.paid do 1º pagamento, se houver)
Alguns dias antes de cada vencimento	—	charge.created da cobrança do ciclo (type = recurring)
Débito no vencimento	—	payment.received e charge.paid
Sem saldo e sem novas tentativas	—	charge.expired
Cliente recusa	rejected	subscription.rejected
Cancelada por você ou pelo cliente	canceled	subscription.canceled (canceled_by: merchant ou payer)

As cobranças de cada ciclo aparecem em /charges com subscription_id, e os pagamentos, devoluções e taxas funcionam como em qualquer cobrança. Como sempre, confirme pela API antes de liberar o serviço (veja webhooks).

Cancelar

POST /v1/subscriptions/{id}/cancel encerra a autorização no banco e cancela as cobranças de ciclos ainda não pagas. O cliente também pode cancelar pelo app do banco dele — você recebe subscription.canceled com canceled_by = payer.

Testar no sandbox

Crie a assinatura com a chave sk_sandbox_… e use simulate_decision com approve, reject ou cancel_by_payer. Para um ciclo, use simulate_payment (débito feito) ou simulate_expiration (débito que não aconteceu) na cobrança do ciclo.