PayZu GatewayCobranças

Vender no cartão


Nesta páginaCobre no cartãoCamposCartãoConfirme o pagamentoErros desta operação

Cobre um valor no cartão de crédito, à vista ou em até 12 parcelas, com a fatura e a tentativa de pagamento criadas na mesma chamada.

Cobre no cartão

bash
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pedido 1234",
    "external_reference": "pedido-1234",
    "amount": 15990,
    "items": [
      { "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 }
    ],
    "customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
    "payment": {
      "method": "credit_card",
      "credit_card": {
        "card": {
          "number": "4111111111111111",
          "expiration": "12/2030",
          "cvv": "123",
          "holder_name": "MARIA SOUZA",
          "holder_document": "52998224725"
        },
        "installments": 1,
        "save_card": true
      }
    },
    "metadata": { "internal_id": "1234" }
  }'

Referência: Criar uma fatura

Um erro antes do envio da cobrança libera a Idempotency-Key.

Valor fora do limite da conta, token inválido, cartão de outro cliente, parcelas ou meio fora do aceito e o pagamento indisponível no momento são erros desse tipo: a fatura não é criada, e você pode repetir com a mesma chave. Se mandou card_token, gere um token novo, porque o token serve para uma operação só.

Campos

A rota é a de Criar uma fatura, com os mesmos campos e o bloco payment.

CampoRegra
payment.methodcredit_card.
payment.credit_card.installmentsDe 1 até payment_settings.credit_card.max_installments da fatura, que vai até 12. Sem ele, 1.
payment.credit_card.save_cardSalva o cartão no cliente, como explica a seção Cartão.
customer_id ou customerObrigatório com payment: a fatura sem cliente só é paga pela página.
Idempotency-KeyCabeçalho obrigatório, com um valor novo para cada venda. Veja Idempotência.

Parcelas acima do aceito ou credit_card fora de payment_settings.accepted_methods respondem 400, com payment.credit_card.installments ou payment.method em fields.

Cartão

O cartão vai em payment.credit_card, por um destes três campos:

CampoCartão
cardDigitado no seu sistema, com number, expiration no formato MM/AAAA, cvv, holder_name e, se quiser, holder_document.
card_idSalvo no mesmo cliente, como em Cartões salvos. Um card_id que não é de um cartão salvo do cliente da fatura responde 404.
card_tokenCifrado no aparelho do comprador, como em Tokenização de cartão. O token vale 15 minutos e serve para uma operação só.
  • save_card: true: salva o cartão de card ou de card_token no cliente, e o id dele vem em payments[0].credit_card.card.id para as próximas cobranças. Se a primeira cobrança desse cartão for recusada, ele é apagado.
  • Sem save_card: com card ou card_token, card.id vem null. Com card_id, vem o id do cartão salvo.
  • holder_document: é só de entrada e não volta em nenhuma resposta.

A cobrança no cartão pela API não leva dados de antifraude nem de 3D Secure. Se a sua conta exige antifraude no cartão, a cobrança é recusada, e o Pix segue disponível.

Confirme o pagamento

Criada a fatura, a resposta é 201, com a tentativa em payments[0], inclusive quando ela vem failed ou processing.

ResultadoTentativaFaturaEvento
Cartão aprovadopaidpaidinvoice.paid
Recusa do banco, do antifraude ou da operaçãofailed, com o motivo em failurependinginvoice.payment_failed
A adquirente não respondeu a tempoprocessingpending-

A tentativa processing se resolve sozinha e passa a paid ou a failed:

  • A PayZu procura a cobrança na adquirente a partir de 5 minutos da criação.
  • Sem cobrança em 30 minutos, ou com a cobrança ainda sem resposta em 24 horas, a tentativa passa a failed e a fatura volta a aceitar tentativa.
  • Se a cobrança aparecer depois, aprovada, a tentativa ainda passa a paid.

Enquanto a tentativa estiver processing, não crie outra fatura para o mesmo pedido.

Uma nova tentativa na mesma fatura é recusada até o desfecho. Nas 24 horas seguintes, repetir a mesma criação com a mesma Idempotency-Key retorna a resposta guardada, com Idempotent-Replayed: true, sem cobrar de novo; o número, o CVV e o token do cartão não entram nessa comparação. Trocar o token pelo cartão digitado, ou o contrário, responde 409, assim como a repetição feita antes de a primeira chamada terminar.

Na recusa, failure diz onde a venda parou. failure.code é o código estável da recusa e failure.message é a frase pronta para mostrar ao cliente.

failure.stageOnde a venda parou
issuerO banco do cliente negou.
antifraudO antifraude parou a venda antes do banco.
card_checkA validade não confere com a do cartão.
splitFalha na divisão do valor da venda.
processingFalha na operação, sem resposta do banco.
Trecho da resposta com o cartão recusado
{
  "id": "in_9Lq4ZnWcVb7TyXm3KdRh2E",
  "status": "pending",
  "payments": [
    {
      "id": "pay_6TzR2nXcVb8LwYm4KdQh9E",
      "status": "failed",
      "method": "credit_card",
      "amount": 15990,
      "failed_at": "2026-11-11T15:22:41.925Z",
      "failure": {
        "stage": "issuer",
        "code": "PZ230",
        "message": "O banco do cliente recusou sem dizer o motivo. O cliente pode usar outro cartão ou falar com o banco."
      }
    }
  ]
}

A recusa não fecha a fatura: a url segue valendo para o cliente pagar na página, e você pode tentar de novo pela API, como em Pagar uma fatura.

Os eventos trazem a fatura em data.invoice, no formato da resposta. Cadastre o webhook em Cadastrar webhooks e, para conferir um caso específico, consulte a fatura.

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.
-404Cliente não encontrado para o id informado.
-404Cartão não encontrado para o id informado.
PZ100422A soma dos itens é diferente do valor da fatura.
PZ101422Valor fora do limite desta conta.
PZ203422Esta conta exige os dados de antifraude na cobrança no cartão.
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.