Skip to main content
A fatura (inv_) é o documento de cobrança que uma assinatura emite a cada ciclo. Ela reúne os itens cobrados, tem um total em centavos e percorre um ciclo de vida próprio, independente do da assinatura que a gerou. Pela API, a fatura é somente leitura: quem a cria é o motor de cobrança, no ritmo da recorrência. O que se faz aqui é acompanhar — e distribuir o link de pagamento.
Todas as rotas exigem o header x-api-key. Veja Autenticação. Valores monetários são sempre inteiros em centavos (18990 = R$ 189,90).

​
Endpoints

Não há rota de escrita. Criar fatura avulsa, gerar link de pagamento, reagendar e forçar uma nova cobrança são ações do painel do lojista, com sessão de usuário — não estão expostas por x-api-key. Pela API você lê o que o motor produziu.

​
Os oito estados

Não existe status voided. O webhook chama-se invoice.voided, mas o campo status da fatura anulada é canceled. Uma integração que procure voided no objeto nunca vai encontrar. Ver o catálogo de eventos.
suspended só existe em assinatura upfront pausada. Na pausa de uma just_in_time, as faturas não pagas são anuladas em vez de congeladas. A suspensa tem duas saídas: a retomada a devolve para scheduled com as datas deslocadas, e o cancelamento a leva para canceled. Enquanto suspensa, ela não é pagável — o link público responde 404.
paid, canceled, refunded e unpaid são terminais e recusam ação de cancelamento.
Você não precisa construir tela de pagamento nem de troca de cartão: a Z2Pay hospeda as duas e entrega o link pronto. O seu papel é distribuí-lo — por e-mail, no seu app, onde fizer sentido. Link da fatura — /i/{token}, onde o token é o publicAccessToken da fatura. O pagador abre e a slip de PIX ou boleto é gerada na hora, em vez de expirar dentro de um e-mail antigo. O que ele vê depende do estado: Link de troca de forma de pagamento — o paymentUpdateToken da assinatura (prefixo pmt_), exposto no objeto dela. É por aqui que o cliente final atualiza o cartão quando ele vence ou é recusado, sem falar com você.
Os dois tokens são credencial, não identificador. Quem tem o itk_ abre aquela fatura; quem tem o pmt_ troca o cartão daquela assinatura — sem login, porque é assim que o cliente final consegue pagar. Trate-os como senha: entregue ao titular pelo seu canal, e não os deixe em log de aplicação nem em URL de analytics.A listagem devolve um itk_ por fatura, então logar o corpo inteiro de uma página espalha vários de uma vez.
O link de troca só vale em assinatura já ativada. Numa incomplete, a primeira forma de pagamento entra pelo Checkout ou por POST /subscriptions/{id}/payment-method — ver Assinaturas.
As rotas que essas páginas chamam por trás não são da API pública. Elas se autenticam pela posse do token, não por x-api-key, e existem para o nosso próprio front. Quem for montar a própria página de pagamento monta o fluxo pelas rotas autenticadas, não por essas.

​
Veja também

Assinaturas

O contrato que emite as faturas.

Ciclos

Quando cada fatura nasce, vence e é cobrada.

Planos e Preços

Os valores que compõem os itens da fatura.

Tokenizer

Tokenize cartões no navegador do cliente.