Pagar a fatura pela página
Nesta página
Consulte a faturaPague a faturaFatura sem clienteQuando a fatura aceita a tentativaConfira o resultadoAcompanhe o PixNa fatura de linkErros desta operaçãoCobre 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
curl https://api.sandbox.payzu.dev/v1/checkout/invoices/in_3RtY8mKcVb5NwXz2QdLh7E{
"id": "in_3RtY8mKcVb5NwXz2QdLh7E",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_3RtY8mKcVb5NwXz2QdLh7E",
"description": "Pedido 1236",
"created_at": "2026-11-11T15:24:10.512Z",
"updated_at": "2026-11-11T15:24:10.512Z",
"amounts": {
"subtotal": 20980,
"discount": 0,
"total": 20980,
"paid": 0,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-18T03:00:00.000Z",
"expires_at": "2026-11-25T03:00:00.000Z",
"paid_at": null,
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 },
{ "name": "Apostila impressa", "sku": null, "quantity": 2, "unit_price": 2495 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"redirect_url": "https://loja.exemplo.com.br/obrigado",
"cancel_url": "https://loja.exemplo.com.br/carrinho"
},
"merchant": {
"display_name": "Loja da Maria"
},
"customer": {
"name": "Maria",
"email": "m***@exemplo.com.br",
"document": "***.982.247-**",
"document_type": "cpf",
"phone": "(11) *****-4321",
"address_on_file": true
},
"subscription": null,
"payment_link": null,
"payments": [],
"refunds": []
}Referência: Consultar uma fatura pela página
A consulta responde a fatura em qualquer status, sem metadata nem external_reference.
| Campo | O que traz |
|---|---|
payment_settings | Os 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. |
customer | O 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_file | true quando o cliente já tem endereço completo. Com false, peça o endereço de cobrança antes do cartão. |
subscription, payment_link | De onde a fatura veio. payment_link.discount traz o desconto do link, para a página mostrar a oferta. |
payments | As 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
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"
}
}'{
"id": "in_3RtY8mKcVb5NwXz2QdLh7E",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_3RtY8mKcVb5NwXz2QdLh7E",
"description": "Pedido 1236",
"created_at": "2026-11-11T15:24:10.512Z",
"updated_at": "2026-11-11T15:26:02.414Z",
"amounts": {
"subtotal": 20980,
"discount": 0,
"total": 20980,
"paid": 20980,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-18T03:00:00.000Z",
"expires_at": "2026-11-25T03:00:00.000Z",
"paid_at": "2026-11-11T15:26:02.412Z",
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 },
{ "name": "Apostila impressa", "sku": null, "quantity": 2, "unit_price": 2495 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 3 }
},
"checkout": {
"redirect_url": "https://loja.exemplo.com.br/obrigado",
"cancel_url": "https://loja.exemplo.com.br/carrinho"
},
"merchant": {
"display_name": "Loja da Maria"
},
"customer": {
"name": "Maria",
"email": "m***@exemplo.com.br",
"document": "***.982.247-**",
"document_type": "cpf",
"phone": "(11) *****-4321",
"address_on_file": true
},
"subscription": null,
"payment_link": null,
"payments": [
{
"id": "pay_8LqZ3nWcVb5TyXm2KdRh7E",
"status": "paid",
"method": "credit_card",
"amount": 20980,
"created_at": "2026-11-11T15:26:02.108Z",
"paid_at": "2026-11-11T15:26:02.412Z",
"failed_at": null,
"failure": null,
"credit_card": {
"installments": 3,
"authorization_code": "123456",
"card": { "brand": "visa", "last_digits": "1111" }
}
},
{
"id": "pay_5NwK7xQcLb3MzYv9TdRh2E",
"status": "failed",
"method": "credit_card",
"amount": 20980,
"created_at": "2026-11-11T15:25:31.040Z",
"paid_at": null,
"failed_at": "2026-11-11T15:25:31.764Z",
"failure": {
"stage": "issuer",
"code": "PZ250",
"message": "O cartão não tem saldo ou limite para este valor. O cliente pode usar outro cartão."
},
"credit_card": {
"installments": 3,
"authorization_code": null,
"card": { "brand": "mastercard", "last_digits": "5454" }
}
}
],
"refunds": []
}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.
| Campo | Regra |
|---|---|
method | credit_card ou pix, entre os de payment_settings.accepted_methods. |
credit_card.card | O cartão digitado, com number, expiration no formato MM/AAAA, cvv, holder_name e, se quiser, holder_document. |
credit_card.installments | De 1 até payment_settings.credit_card.max_installments. Sem ele, 1. |
address | Opcional, 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_analysis | Opcional, 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. |
customer | Só na fatura sem cliente, em que é obrigatório. Veja Fatura sem cliente. |
- Só o cartão digitado:
card_id,card_tokenesave_cardrespondem400, como qualquer campo fora da tabela. - Meio e parcelas: meio fora de
accepted_methodsou parcelas acima demax_installmentsrespondem422. - 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.
{
"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ção | Resposta |
|---|---|
Fatura sem cliente e corpo sem customer | 400, com customer em fields e a mensagem Dados do cliente são obrigatórios. |
Fatura com cliente e corpo com customer | 400, 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
pendingrecebe tentativa. Apendingque já passou debilling.expires_até fechada comoexpiredna 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
activeou, na fatura de adesão, com a assinaturaincomplete. Paga a adesão, a assinatura passa aactive; no cartão, a recorrência fica no cartão cobrado. Um503na adesão no cartão sai sem cobrança, e você pode tentar de novo.
Confira o resultado
| Resultado | Tentativa | Fatura | Evento |
|---|---|---|---|
| Cartão aprovado | paid | paid | invoice.paid |
| Cartão recusado | failed, com o motivo em failure | pending | invoice.payment_failed |
| A adquirente não respondeu a tempo | processing | pending | - |
| Pix gerado | pending, com o QR Code em pix | pending | invoice.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
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/invoices/in_5Hn9WqZc2LmXv6BtYr1dKe/payments \
-H "Content-Type: application/json" \
-d '{ "method": "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, porqueqr_code_urlvem semprenull. - Validade: o QR Code vale 60 minutos, até
pix.expires_at. Vencido sem pagamento, a tentativa passa aexpired, e um novo pedido de Pix gera outro QR Code. - Confirmação: consulte a fatura até
statussair dependingou a tentativa Pix passar aexpired. Com a fatura aindapendinge sem tentativa de cartãoprocessing, ofereça outro Pix. Cada consulta conta no limite de 60 por minuto por IP.
Na fatura de link
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
422até o QR Code vencer. - Desconto: paga com o meio de
payment_link.discount.payment_method, a tentativa sai com o valor descontado, eamounts.discounteamounts.totalpassam 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ódigo | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ030 | 403 | Gateway suspenso para esta conta. Fale com o suporte PayZu. |
| - | 404 | Fatura não encontrada para o id informado. |
PZ110 | 409 | Esta fatura já foi paga. |
PZ111 | 409 | Só uma fatura em aberto pode ser paga ou cancelada. |
PZ112 | 409 | Esta fatura já está sendo cobrada. Aguarde um instante. |
PZ113 | 409 | Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde. |
PZ101 | 422 | Valor fora do limite desta conta. |
PZ114 | 422 | Limite diário de tentativas de cobrança desta fatura atingido. Tente novamente mais tarde. |
| - | 422 | Meio de pagamento não aceito nesta fatura. |
| - | 422 | Número de parcelas acima do aceito nesta fatura. |
| - | 422 | Este link já foi pago. |
| - | 422 | Este link foi cancelado. |
| - | 422 | Este link expirou. |
| - | 422 | Este link atingiu o limite de pagamentos. |
| - | 422 | Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos. |
| - | 422 | Limite de tentativas atingido. Tente novamente mais tarde. |
| - | 429 | Muitas tentativas. Aguarde um minuto. |
PZ202 | 503 | Não foi possível processar o cartão agora. Tente de novo. |
PZ900 | 503 | Não foi possível processar o pagamento agora. Tente novamente mais tarde. |
Os erros de validação estão no Catálogo de erros.