PayZu GatewayCobranças

Vender no Pix


Nesta páginaCobre no PixMostre o copia e colaConfirme o pagamentoErros desta operação

Crie a fatura com um QR Code do Pix que vale pelo prazo que você definir, de 1 minuto a 2 horas.

Cobre no Pix

bash
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Idempotency-Key: 7d2e9b4c-1f3a-4c8e-b5d6-0a9f8e7c6b5a" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pedido 1235",
    "external_reference": "pedido-1235",
    "amount": 5990,
    "customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
    "payment": {
      "method": "pix",
      "pix": { "expires_in": 3600 }
    }
  }'

Referência: Criar uma fatura

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

CampoRegra
payment.methodpix.
payment.pix.expires_inOpcional: a validade do QR Code em segundos, de 60 a 7200. Sem ele, 1 hora. O prazo para pagar a fatura é billing.expires_at.
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.

Com pix fora de payment_settings.accepted_methods, a criação responde 400, com payment.method em fields.

Mostre o copia e cola

A fatura volta pending, com a tentativa em payments[0]. Com a tentativa pending, o copia e cola vem em pix.qr_code_text e o fim da validade do QR Code em pix.expires_at; nos outros resultados da tabela, não há QR Code para mostrar. A API não traz a imagem do QR Code: mostre o copia e cola com um botão de copiar e gere a imagem a partir dele.

ResultadoTentativaResposta
QR Code emitidopending, com o bloco pix201, com a fatura
Pix recusado na emissãofailed, com o motivo em failure201, com a fatura
A adquirente não respondeu a tempoprocessing, sem o QR Code201, com a fatura

A tentativa processing se resolve sozinha: quando a cobrança aparece, ela passa a pending, com o QR Code, sem evento. Consulte a fatura para pegar o copia e cola. Se a cobrança não aparece em 30 minutos, ou segue sem desfecho por 24 horas, a tentativa passa a failed, com o motivo em failure, e o QR Code não vem mais.

Pedir Pix de novo com o QR Code ainda válido retorna o mesmo QR Code.

A nova tentativa é feita em Pagar uma fatura. O Pix pendente não impede pagar a mesma fatura no cartão; se os dois forem pagos, o segundo pagamento é devolvido sozinho.

Confirme o pagamento

O que aconteceuTentativaFaturaEvento
O Pix foi pago.paid, com paid_at e o identificador da transação em pix.end_to_end_idpaidinvoice.paid
O QR Code venceu sem pagamento.expiredpending-
billing.expires_at chegou sem pagamento.como estavaexpiredinvoice.expired

Com o QR Code vencido e a fatura ainda pending, peça outro Pix ou mande a url ao cliente. Um Pix pago depois de a fatura ficar canceled ou expired ainda é aceito: a fatura volta a paid e sai invoice.paid. pix.payer traz o nome e o documento de quem pagou quando a informação chega com o pagamento; sem ela, vem null.

Recomendamos acompanhar a venda por um webhook, cadastrado em Cadastrar webhooks. O evento traz a fatura em data.invoice, no formato da resposta. Para conferir o estado atual, consulte a fatura. Para um evento que não chegou, consulte a entrega e reenvie.

Erros desta operação

CódigoHTTPMensagem
PZ001400A solicitação possui erros de validação.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
-404Cliente não encontrado para o id informado.
PZ100422A soma dos itens é diferente do valor da fatura.
PZ101422Valor fora do limite desta conta.
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.