Garu

2026-05-29

v0.14.0 — Pix Automático nas assinaturas: o cliente assina direto pelo checkout do produto

subscriptionsassinaturaspixpix-automaticocheckoutbilling

O que muda no checkout

Na v0.13.0 lançamos Pix Automático em cobranças agendadas (criadas pelo painel). Era útil para cobranças pontuais, mas o ponto onde sua receita recorrente realmente acontece é o checkout público de produtos com assinatura — e lá só dava para pagar com Cartão.

Agora a página /pay/<produto>?priceId=<plano> mostra Pix Automático como uma nova aba ao lado de Cartão (quando o produto está marcado como pixAutomatic, o padrão para todos os produtos de assinatura). O fluxo é:

  1. Cliente escolhe a aba Pix Automático, preenche nome/CPF/e-mail/telefone (sem cartão).
  2. Ao confirmar, a mesma página exibe o QR Code de autorização do Pix Automático do Banco Central.
  3. Cliente escaneia no app do banco e autoriza uma única vez.
  4. A página atualiza sozinha quando a autorização cai e mostra a tela de assinatura confirmada.
  5. A partir do próximo ciclo, as cobranças acontecem sozinhas — o débito cai na data e o período da assinatura avança automaticamente.

Renovações, falhas de cobrança, "past_due" depois de N tentativas, cancelamento — tudo passa pela mesma máquina de estado já usada pelas assinaturas de cartão.

Para desenvolvedores

  • POST /api/subscribe agora aceita paymentMethod: 'pix_automatic'. Quando presente, o creditCard é dispensado e a resposta inclui brCode + qrCodeImage + subscriptionUuid em vez de uma Charge quitada.
  • Novo GET /api/subscribe/:uuid/status (público) para o polling da página de consentimento. Usa o UUID da assinatura — não o id sequencial — para não ser enumerável.
  • Nova flag por produto product.pixAutomatic (padrão ON). O toggle no painel chega em seguida; até lá, dá para desligar via banco se algum produto não deve oferecer Pix Automático.
  • Kill switch operacional disponível em caso de emergência: parar a criação de novas assinaturas Pix Automático na hora sem redeploy. Assinaturas ativas continuam sendo cobradas normalmente.
  • Wrappers de SDK e ferramenta MCP para o novo paymentMethod chegam em seguida nos repositórios públicos.

Limitações conhecidas (próximos passos)

  • Sem período de teste por enquanto: assinaturas com trialPeriodDays > 0 ainda recusam Pix Automático até validarmos o agendamento da primeira cobrança.
  • Troca de método em assinatura ativa: um cliente que hoje paga no cartão ainda não consegue trocar a forma de pagamento da assinatura ativa para Pix Automático. Cancelar + reassinar funciona. A troca direta vem na próxima minor.