pxa_) é o consentimento que o pagador dá, no app do banco
dele, para que as faturas seguintes de uma assinatura sejam debitadas da conta sem que ele precise
fazer nada. Ela nasce junto com o primeiro pagamento — o mesmo QR cobra agora e pede a autorização —
e depois vira a forma de pagamento da assinatura, no lugar que o cartão (crd_) ocuparia.
A confirmação acontece fora da sua tela, no app do banco. É por isso que o fluxo depende de
webhook: só o evento pix_authorization.activated diz que o pagador autorizou e que você já pode
criar a assinatura. E do segundo ciclo em diante não há chamada nenhuma a fazer — a fatura de cada
renovação é debitada no vencimento.
Todas as rotas exigem o header
x-api-key (sua chave de sandbox). Veja
Autenticação. O Pix Automático é liberado por conta: sem ele habilitado, a
abertura da autorização responde 409 — fale com o suporte para habilitar.Endpoints
Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.Do QR ao débito automático
A assinatura precisa caber no que se debita sozinho. Periodicidade semanal, mensal (inclusive
trimestral e semestral) ou anual — a diária não é aceita;
collectionTiming: "prepaid" (o
default); e uma fatura por ciclo (invoiceGenerationMode: "just_in_time", o default —
upfront, que emite todas as faturas de uma vez, é recusado). O maxCycles é aceito: quando a
assinatura cumpre todos os ciclos, a autorização é encerrada junto. A frequency da autorização
tem de ser a da assinatura. Fora disso, o POST /subscriptions responde 409 e nenhuma
assinatura é criada — o mesmo vale para uma autorização já encerrada ou vinculada a outra
assinatura.Status da autorização
O status muda pelo que acontece no banco do pagador e pelo que você (ou a própria assinatura) faz. Toda mudança gera um webhook, exceto a abertura: quem abriu recebe opending na resposta.
canceled e expired são finais: uma autorização encerrada não volta, e uma nova adesão cria outra,
com outro id.
Trate o
pix_authorization.canceled. Quando é o pagador quem revoga, no app do banco, esse
evento é a única notícia que você recebe. A assinatura continua — parar o débito não cancela o
contrato —, e as faturas seguintes passam a ir por e-mail, com o link para pagar por Pix.Quando é o contrato que acaba, o evento da assinatura chega junto (subscription.canceled ou
subscription.completed) e não há o que cobrar: não peça uma nova autorização nesse caso.O débito de cada ciclo
Do segundo ciclo em diante, o que você observa é a fatura da renovação:
Não existe um evento próprio para “debitado”: o resultado chega pelos eventos de fatura e de
pagamento. Enquanto o débito está pedido, o pagador não recebe e-mail de fatura disponível nem
lembrete de vencimento — não há nada para ele pagar. Abertura e vencimento não são deslocados para
dia útil: caem no dia exato, que é o que o app do banco mostra ao pagador.
Se o banco recusar o agendamento, a fatura vai por link — e não entra em atraso. A recusa pode
vir na hora do pedido ou minutos depois, quando o banco do pagador recebe o agendamento. Nesse
caso o pagamento do débito passa a
refused (evento payment.refused), o pagador recebe o e-mail
com o link para pagar por Pix, e a régua de cobrança só começa se o vencimento passar sem
pagamento. Já a falha no dia do desconto — sem saldo, por exemplo — é do pagador e segue a
régua normal.O pagador pode limitar o valor no aplicativo do banco. Ao autorizar o Pix Automático, ou
depois, o pagador pode definir um valor máximo por débito. Se uma fatura passar desse valor, o
banco recusa o agendamento e vale o que está acima: o pagador recebe o link para pagar essa fatura
por Pix. O débito automático volta nos ciclos seguintes se o valor couber no limite ou se o pagador
aumentar o limite no aplicativo. A API não informa o motivo da recusa.
Algumas faturas nunca vão a débito — seguem por link, como Pix comum. A fatura acima de
2× o valor recorrente da assinatura (a soma de quantidade × preço dos itens ativos), para que o
pagador veja o valor antes de pagar; a fatura avulsa, lançada fora do ciclo — para um valor extra
ser debitado, lance-o como cobrança extra, que entra na próxima fatura do ciclo; a fatura criada
com
collectionMethod: "send_invoice"; e qualquer fatura sem autorização active no contrato.
Multa, juros e proração dentro do teto são debitados normalmente.Pelo Checkout, sem integrar estas rotas
Quem vende por um Link de assinatura ou por uma venda rápida de assinatura não chama nada disto: a autorização é proposta e confirmada na página hospedada, e a assinatura nasce sozinha. As regras são as mesmas daqui, e o Checkout recusa ainda a venda com período de teste, com cobrança no fim do ciclo, com número fixo de ciclos (maxCycles) e, na venda rápida, com data de início agendada (startAt).
As autorizações abertas pelo Checkout também geram os eventos pix_authorization.*. Nelas, o
activated chega com subscriptionId: null, porque a assinatura nasce logo depois; e um canceled
ou expired com subscriptionId: null é uma autorização que nunca virou assinatura — o comprador
voltou ao formulário, recusou ou deixou vencer no banco. Não há nada a fazer nesses casos.
Veja também
Assinaturas
Como a assinatura nasce e os estados pelos quais ela passa depois do débito.
Faturas
A fatura de cada ciclo — é por ela que você vê o débito liquidado.
Eventos de webhook
O corpo de cada evento, incluindo os de autorização e os de fatura paga.
Links de checkout
A página hospedada que propõe a autorização por você.