Pagar uma fatura
Tente de novo uma fatura em aberto pela API, depois de uma recusa ou quando o cliente quiser trocar o cartão ou o meio de pagamento.
Pague a fatura
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_3RtY8mKcVb5NwXz2QdLh7E/payments \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 9c4e1a7b-2d3f-4b5a-8e6c-7f0d1a2b3c4d" \
-H "Content-Type: application/json" \
-d '{
"method": "credit_card",
"credit_card": {
"card_id": "card_GL2pIWf5pznF4qwg2KKd5v",
"installments": 3
}
}'{
"id": "in_3RtY8mKcVb5NwXz2QdLh7E",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_3RtY8mKcVb5NwXz2QdLh7E",
"description": "Pedido 1236",
"external_reference": "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"
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"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": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}
},
{
"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": {
"id": null,
"brand": "mastercard",
"last_digits": "5454",
"holder_name": "MARIA SOUZA"
}
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": {
"internal_id": "1234"
}
}Referência: Pagar uma fatura
A resposta é 201, com a fatura inteira. A tentativa nova vem em payments[0], e as anteriores seguem na lista, da mais nova para a mais antiga. 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. Na resposta repetida pela mesma Idempotency-Key, confira pix.expires_at: vencido, consulte a fatura antes de pedir outro Pix.
Monte o corpo
O corpo é o objeto payment de Criar uma fatura, sem a chave payment em volta.
| Campo | Regra |
|---|---|
method | credit_card ou pix, entre os de payment_settings.accepted_methods da fatura. |
credit_card | Um só entre card_id, card_token e card, como em Vender no cartão, com installments e save_card. |
pix.expires_in | Opcional: a validade do QR Code em segundos, de 60 a 7200. Sem ele, 1 hora. |
| Sem corpo | Só na fatura de assinatura: cobra o cartão salvo da assinatura ou, na assinatura no Pix, gera o QR Code. |
Idempotency-Key | Cabeçalho obrigatório, com um valor novo para cada tentativa. |
Meio fora de accepted_methods ou parcelas acima de credit_card.max_installments respondem 400, com method ou credit_card.installments em fields.
Quando a fatura aceita a tentativa
- Status: só a fatura
pendingrecebe tentativa. Apendingque já passou debilling.expires_até fechada comoexpiredna chamada, sem tentativa. - Cartão sem resposta: enquanto uma tentativa de cartão está
processing, uma nova é recusada. - Pix pendente: não impede pagar no cartão. Pedir Pix de novo com o QR Code ainda válido retorna a fatura com o mesmo QR Code.
- Limite: cada fatura aceita até 5 tentativas em 24 horas, contadas a partir da primeira e somadas às feitas na página de pagamento.
- Fatura sem cliente: só é paga pela página, em
url. - Fatura de link: segue também as condições do link, como em Pagar uma fatura pela página: link
active, dentro do prazo e com vaga. Fora delas, a resposta é422, sem cobrar. - Fatura de assinatura: só com a assinatura
activeou, na fatura de adesão, com a assinaturaincompletee o meio de pagamento dela. A adesão que passou debilling.expires_atnão aceita tentativa. Veja Criar uma assinatura.
O resultado segue a tabela de Vender no cartão: cartão aprovado deixa a fatura paid e sai invoice.paid; recusado, a tentativa fica failed, a fatura segue pending e sai invoice.payment_failed.
Use uma Idempotency-Key nova a cada tentativa.
Depois que a cobrança sai para a adquirente, a resposta fica guardada na chave, inclusive a do cartão recusado: repetir a mesma chamada com a mesma chave retorna a recusa anterior, com Idempotent-Replayed: true, sem cobrar de novo, mesmo com outro token. Trocar o token pelo cartão digitado, ou o contrário, responde 409. Um erro antes do envio libera a chave.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
| - | 404 | Fatura não encontrada para o id informado. |
| - | 404 | Cartão não encontrado 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. |
PZ115 | 422 | O cartão da assinatura não está salvo. |
PZ117 | 422 | Fatura sem cliente só é paga pela página de pagamento. |
PZ203 | 422 | Esta conta exige os dados de antifraude na cobrança no cartão. |
| - | 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. |
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 autenticação e de idempotência estão no Catálogo de erros.