PayZu GatewayCheckout

Pagar a fatura pela página


Nesta páginaConsulte a faturaPague a faturaFatura sem clienteQuando a fatura aceita a tentativaConfira o resultadoAcompanhe o PixNa fatura de linkErros desta operação

Cobre uma fatura em aberto numa página sua, com as rotas que a página de pagamento da url da fatura usa. Elas não pedem chave, porque o id da fatura identifica a cobrança. Para criar a fatura pela API, veja Criar uma fatura.

Consulte a fatura

bash
curl https://api.sandbox.payzu.dev/v1/checkout/invoices/in_3RtY8mKcVb5NwXz2QdLh7E

Referência: Consultar uma fatura pela página

A consulta responde a fatura em qualquer status, sem metadata nem external_reference.

CampoO que traz
payment_settingsOs meios que a fatura aceita e que a sua conta recebe, com o máximo de parcelas. credit_card vem null quando o cartão não está entre os meios.
customerO primeiro nome do cliente, com o e-mail, o documento e o celular mascarados. Vem null na fatura sem cliente, até a primeira tentativa.
customer.address_on_filetrue quando o cliente já tem endereço completo. Com false, peça o endereço de cobrança antes do cartão.
subscription, payment_linkDe onde a fatura veio. payment_link.discount traz o desconto do link, para a página mostrar a oferta.
paymentsAs tentativas, da mais nova para a mais antiga, sem o titular nem o id do cartão.

Paga, a fatura é o comprovante da compra. No cartão, a tentativa traz a bandeira, o final, as parcelas e o código de autorização; no Pix, o copia e cola e o end_to_end_id. Os status da fatura estão em Cobranças.

Pague a fatura

bash
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/invoices/in_3RtY8mKcVb5NwXz2QdLh7E/payments \
  -H "Content-Type: application/json" \
  -d '{
    "method": "credit_card",
    "credit_card": {
      "card": {
        "number": "4111111111111111",
        "expiration": "12/2030",
        "cvv": "123",
        "holder_name": "MARIA SOUZA",
        "holder_document": "52998224725"
      },
      "installments": 3
    },
    "fraud_analysis": {
      "finger_print_id": "3f2a9c1e-5b7d-4e80-a6c4-1d9e8f7b2a35",
      "cookies_accepted": true,
      "browser_type": "Chrome"
    }
  }'

Referência: Pagar uma fatura pela página

A resposta é 201, com a fatura na mesma visão da consulta. A tentativa nova vem em payments[0], e as anteriores seguem na lista. O Pix pedido de novo com o QR Code ainda válido não cria tentativa: localize a tentativa com method pix e status pending.

CampoRegra
methodcredit_card ou pix, entre os de payment_settings.accepted_methods.
credit_card.cardO cartão digitado, com number, expiration no formato MM/AAAA, cvv, holder_name e, se quiser, holder_document.
credit_card.installmentsDe 1 até payment_settings.credit_card.max_installments. Sem ele, 1.
addressOpcional, só no cartão. O endereço de cobrança, com zip_code, number, street, district, city e state, que passa a ser o endereço do cliente. Envie quando customer.address_on_file vier false.
fraud_analysisOpcional, só no cartão. Os dados do aparelho do comprador para a análise antifraude: finger_print_id, um UUID, cookies_accepted e, se quiser, browser_type.
customerSó na fatura sem cliente, em que é obrigatório. Veja Fatura sem cliente.
  • Só o cartão digitado: card_id, card_token e save_card respondem 400, como qualquer campo fora da tabela.
  • Meio e parcelas: meio fora de accepted_methods ou parcelas acima de max_installments respondem 422.
  • Sem idempotência: a rota não usa Idempotency-Key. Cada chamada é uma tentativa nova, salvo o Pix com o QR Code ainda válido.

Fatura sem cliente

Na fatura com customer: null, a primeira tentativa leva os dados de quem paga, com os campos de Cadastrar um cliente, sem metadata.

Corpo na fatura sem cliente
{
  "customer": {
    "name": "João Lima",
    "email": "joao@exemplo.com.br",
    "document": "11144477735",
    "document_type": "cpf",
    "phone": "21998765432",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 12",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01310100",
      "country": "BR"
    }
  },
  "method": "pix"
}

A PayZu cadastra o cliente pelo document ou atualiza o que já tem esse documento. Ele fica ligado à fatura na primeira tentativa, mesmo recusada, e as tentativas seguintes vão sem customer. Daí em diante, a fatura também pode ser paga pela API, como em Pagar uma fatura.

SituaçãoResposta
Fatura sem cliente e corpo sem customer400, com customer em fields e a mensagem Dados do cliente são obrigatórios.
Fatura com cliente e corpo com customer400, com customer em fields e a mensagem Esta fatura já tem cliente. Envie o pagamento sem os dados do cliente.

Quando a fatura aceita a tentativa

  • Status: só a fatura pending recebe tentativa. A pending que já passou de billing.expires_at é fechada como expired na chamada, sem tentativa.
  • Ao mesmo tempo: com uma cobrança da fatura em andamento, pela página ou pela API, outra chamada é recusada.
  • Cartão sem resposta: enquanto uma tentativa de cartão está processing, por até 24 horas, uma nova é recusada.
  • Pix pendente: não impede pagar no cartão. Pedir Pix de novo com o QR Code ainda válido retorna o mesmo QR Code, sem tentativa nova.
  • Limite: cada fatura aceita até 5 tentativas em 24 horas, contadas a partir da primeira e somadas às feitas pela API.
  • Fatura de assinatura: só com a assinatura active ou, na fatura de adesão, com a assinatura incomplete. Paga a adesão, a assinatura passa a active; no cartão, a recorrência fica no cartão cobrado. Um 503 na adesão no cartão sai sem cobrança, e você pode tentar de novo.

Confira o resultado

ResultadoTentativaFaturaEvento
Cartão aprovadopaidpaidinvoice.paid
Cartão recusadofailed, com o motivo em failurependinginvoice.payment_failed
A adquirente não respondeu a tempoprocessingpending-
Pix geradopending, com o QR Code em pixpendinginvoice.paid, quando o cliente paga

A recusa não fecha a fatura, e o comprador pode tentar outro cartão ou o Pix. Os estágios de failure e a resolução da tentativa processing estão em Vender no cartão.

Uma tentativa processing pode ter sido aprovada.

Mostre ao comprador que o pagamento está em análise, sem pedir outro. A PayZu procura a cobrança na adquirente e resolve a tentativa sozinha; acompanhe pela consulta da fatura ou pelo evento invoice.paid.

Acompanhe o Pix

bash
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/invoices/in_5Hn9WqZc2LmXv6BtYr1dKe/payments \
  -H "Content-Type: application/json" \
  -d '{ "method": "pix" }'
Trecho da resposta no Pix
{
  "id": "in_5Hn9WqZc2LmXv6BtYr1dKe",
  "status": "pending",
  "payments": [
    {
      "id": "pay_EHbu1cBNxmis3c7Ftz2Dg7",
      "status": "pending",
      "method": "pix",
      "amount": 5990,
      "created_at": "2026-11-11T15:20:59.344Z",
      "paid_at": null,
      "failed_at": null,
      "failure": null,
      "pix": {
        "qr_code_text": "00020126MOCKEHbu1cBNxmis3c7Ftz2Dg7",
        "qr_code_url": null,
        "expires_at": "2026-11-11T16:20:59.344Z",
        "end_to_end_id": null
      }
    }
  ]
}
  • QR Code: mostre qr_code_text, o copia e cola, com um botão de copiar, e gere a imagem a partir dele, porque qr_code_url vem sempre null.
  • Validade: o QR Code vale 60 minutos, até pix.expires_at. Vencido sem pagamento, a tentativa passa a expired, e um novo pedido de Pix gera outro QR Code.
  • Confirmação: consulte a fatura até status sair de pending ou a tentativa Pix passar a expired. Com a fatura ainda pending e sem tentativa de cartão processing, ofereça outro Pix. Cada consulta conta no limite de 60 por minuto por IP.

A fatura criada pela compra no link, com payment_link preenchido, segue também as condições do link, conferidas a cada tentativa.

  • Link aberto: a tentativa só sai com o link active, dentro do prazo e com vaga. Fechado, vencido ou sem vaga, a resposta é 422, sem chamar a adquirente.
  • Vaga: cada tentativa ocupa uma vaga do link até o desfecho. A recusa, a falha e o Pix vencido liberam a vaga, o cartão sem resposta da adquirente a segura por até 24 horas, e a fatura paga a confirma. A cobrança aprovada que aparece depois de liberar a vaga ocupa uma livre; sem vaga ou com o link fechado, a fatura fica paga e não conta no limite.
  • Link de uma vaga: com um Pix pendente, o cartão na mesma fatura responde 422 até o QR Code vencer.
  • Desconto: paga com o meio de payment_link.discount.payment_method, a tentativa sai com o valor descontado, e amounts.discount e amounts.total passam a mostrar o desconto. Com o outro meio, a fatura fica no valor cheio.
  • Limite da conta: o limite por cobrança da sua conta é conferido sobre o valor cobrado, já com o desconto.
  • Tentativas: além do limite da fatura, cada cliente faz até 5 tentativas em cada link em 24 horas.

Erros desta operação

CódigoHTTPMensagem
PZ001400A solicitação possui erros de validação.
PZ030403Gateway suspenso para esta conta. Fale com o suporte PayZu.
-404Fatura não encontrada para o id informado.
PZ110409Esta fatura já foi paga.
PZ111409Só uma fatura em aberto pode ser paga ou cancelada.
PZ112409Esta fatura já está sendo cobrada. Aguarde um instante.
PZ113409Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde.
PZ101422Valor fora do limite desta conta.
PZ114422Limite diário de tentativas de cobrança desta fatura atingido. Tente novamente mais tarde.
-422Meio de pagamento não aceito nesta fatura.
-422Número de parcelas acima do aceito nesta fatura.
-422Este link já foi pago.
-422Este link foi cancelado.
-422Este link expirou.
-422Este link atingiu o limite de pagamentos.
-422Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos.
-422Limite de tentativas atingido. Tente novamente mais tarde.
-429Muitas tentativas. Aguarde um minuto.
PZ202503Não foi possível processar o cartão agora. Tente de novo.
PZ900503Não foi possível processar o pagamento agora. Tente novamente mais tarde.

Os erros de validação estão no Catálogo de erros.