PayZu GatewayCobranças

Pagar uma fatura


Nesta páginaPague a faturaMonte o corpoQuando a fatura aceita a tentativaErros desta operação

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

bash
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
    }
  }'

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.

CampoRegra
methodcredit_card ou pix, entre os de payment_settings.accepted_methods da fatura.
credit_cardUm só entre card_id, card_token e card, como em Vender no cartão, com installments e save_card.
pix.expires_inOpcional: a validade do QR Code em segundos, de 60 a 7200. Sem ele, 1 hora.
Sem corpoSó na fatura de assinatura: cobra o cartão salvo da assinatura ou, na assinatura no Pix, gera o QR Code.
Idempotency-KeyCabeç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 pending recebe tentativa. A pending que já passou de billing.expires_at é fechada como expired na 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 active ou, na fatura de adesão, com a assinatura incomplete e o meio de pagamento dela. A adesão que passou de billing.expires_at nã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ódigoHTTPMensagem
PZ001400A solicitação possui erros de validação.
PZ201400Token de cartão inválido ou vencido. Gere o token de novo.
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
-404Fatura não encontrada para o id informado.
-404Cartão não encontrado 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.
PZ115422O cartão da assinatura não está salvo.
PZ117422Fatura sem cliente só é paga pela página de pagamento.
PZ203422Esta conta exige os dados de antifraude na cobrança no cartão.
-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.
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 autenticação e de idempotência estão no Catálogo de erros.