Pix Automático

Para mensalidades, planos e assinaturas. O cliente aprova uma vez no app do banco e, a cada ciclo, o valor sai sozinho da conta dele. Sem boleto, sem lembrete, sem cartão vencendo.

Como funciona

1. Você cria o Pix Automático com o valor e a frequência.
2. A SuyPay devolve um QR Code. Mande para o cliente.
3. Ao escanear, o cliente paga o primeiro ciclo e autoriza os próximos no mesmo passo.
4. Nos próximos ciclos, o banco do cliente paga sozinho no vencimento. Cada ciclo vira uma cobrança normal em Pagamentos, com os mesmos avisos (payment.succeeded, payment.failed).

Quais contas fazem

O provedor oferecer Pix Automático não garante que a sua conta esteja liberada. Em Contas conectadas, abra a conta e marque Liberado, Não liberado ou Ainda não sei. A SuyPay prefere contas confirmadas; se precisar, tenta as que ainda não foram confirmadas. Ela não usa as marcadas como não liberadas. Quando uma autorização funciona, marca a conta como liberada. Se o provedor recusar claramente o acesso ao recurso, marca como não liberada e tenta outra conta compatível.

Criar

Pelo painel, em Pix Automático → Novo Pix Automático. Ou pela API:

curl https://api.suypay.com/v1/subscriptions \
  -H "Authorization: Bearer suy_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "monthly",
    "amount": 4990,
    "description": "Plano mensal",
    "customer": { "name": "Ana Lima", "document": "52998224725" }
  }'

A resposta traz status: "pending" e, em approval.qr_code, o código que o cliente escaneia.

O que você precisa saber:

• CPF ou CNPJ é obrigatório. Na Woovi, o endereço completo do cliente também.
• Valor fixo ou variável. Sem amount, o valor muda a cada ciclo (conta de consumo, por exemplo) e você informa o valor de cada um ao cobrar. Use first_amount para o primeiro.
• Nova tentativa. Com retry: true (padrão), se faltar saldo o banco tenta de novo até 3 vezes em 7 dias.
• Frequências: weekly, monthly, quarterly, semiannually e annually.

Depois da aprovação

Quando o cliente aprova, chega o aviso subscription.activated. Se ele não aprovar a tempo, ou o banco dele não confirmar, chega subscription.refused.

Com valor fixo, a SuyPay cobra cada ciclo sozinho. Com valor variável, cobre quando souber o valor:

curl https://api.suypay.com/v1/subscriptions/sub_.../charge \
  -H "Authorization: Bearer suy_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 7320, "due_date": "2026-11-10" }'

O vencimento precisa ficar entre 2 e 10 dias úteis a partir de hoje. Essa é uma regra do Pix Automático, não da SuyPay.

Cancelar

Em Cancelar no painel ou POST /v1/subscriptions/{id}/cancel. Nenhum ciclo novo é cobrado e o cliente vê o cancelamento no app do banco. O cliente também pode cancelar pelo banco: nesse caso chega subscription.canceled.

Testar

No modo de teste, conecte a conta de teste, crie um Pix Automático e clique em Simular aprovação. O primeiro ciclo aparece pago na hora.