> ## Documentation Index > Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt > Use this file to discover all available pages before exploring further. # Pix Automático > Como funciona o Pix Automático — a autorização do pagador, o débito de cada ciclo da assinatura e como você acompanha tudo por webhook. A **autorização de Pix Automático** (`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](/pt-BR/autenticacao). 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. | Método | Rota | Descrição | | - | - | - | | `POST` | `/pix-authorizations` | [Abre a autorização e devolve o QR do primeiro pagamento](/pt-BR/pix-authorizations/create) | | `GET` | `/pix-authorizations/:id` | [Consulta o estado atual da autorização](/pt-BR/pix-authorizations/get) | | `DELETE` | `/pix-authorizations/:id` | [Encerra a autorização no banco do pagador](/pt-BR/pix-authorizations/delete) | *** ## Do QR ao débito automático | # | Você faz | O que acontece | | - | - | - | | 1 | `POST /pix-authorizations` | A autorização nasce `pending`, com o QR do primeiro pagamento em `charge` | | 2 | Exibe o QR na sua tela | O pagador paga e autoriza no app do banco, num gesto só | | 3 | Recebe `pix_authorization.activated` | A autorização está `active` | | 4 | `POST /subscriptions` com `defaultPaymentMethodRef: { "type": "pix_automatic", "id": "pxa_…" }` | A assinatura nasce vinculada à autorização | | 5 | Nada | Cada renovação é debitada no vencimento — ver [O débito de cada ciclo](#o-débito-de-cada-ciclo) | **O primeiro pagamento é obrigatório.** `firstCharge.amount` precisa ser maior que zero: plano com primeiro mês grátis ou entrada zero não passa por esta rota, e autorizar sem pagar nada não é oferecido em lugar nenhum. Para esses planos, cobre por Pix comum a cada ciclo. **Pix Automático e período de teste não se combinam.** `POST /subscriptions` com `defaultPaymentMethodRef.type: "pix_automatic"` e `trialSpec` com `durationDays` maior que zero responde `409` e nenhuma assinatura é criada. Quem precisa de teste usa cartão. **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 o `pending` na resposta. | Status | O que significa | Quando acontece | | - | - | - | | `pending` | O QR saiu; o pagador ainda não confirmou | Resposta do `POST /pix-authorizations` | | `active` | Autorizada — as faturas do contrato vão a débito | O pagador pagou o QR e autorizou no app do banco. Evento `pix_authorization.activated` | | `canceled` | Encerrada; nenhuma fatura vai mais a débito | Você chamou `DELETE`, cancelou a assinatura, a assinatura cumpriu todos os ciclos (`maxCycles`) ou você trocou a forma de pagamento dela — ou o **pagador revogou no app do banco**. Evento `pix_authorization.canceled` | | `expired` | Encerrada sem ter sido confirmada | O pagador não confirmou no banco dentro do prazo. Evento `pix_authorization.expired` | `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: | Momento | O que acontece | | - | - | | De 3 a 10 dias antes do vencimento (sempre 3 no semanal) | A fatura da renovação é emitida e o débito é pedido ao banco do pagador para o dia do vencimento | | Dia do vencimento | O banco desconta; a fatura é paga e você recebe os mesmos eventos de fatura paga de sempre | 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](/pt-BR/checkout/links) ou por uma [venda rápida](/pt-BR/checkout/charges) 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 Como a assinatura nasce e os estados pelos quais ela passa depois do débito. A fatura de cada ciclo — é por ela que você vê o débito liquidado. O corpo de cada evento, incluindo os de autorização e os de fatura paga. A página hospedada que propõe a autorização por você. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.