Vender no Pix
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
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 }
}
}'{
"id": "in_5Hn9WqZc2LmXv6BtYr1dKe",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_5Hn9WqZc2LmXv6BtYr1dKe",
"description": "Pedido 1235",
"external_reference": "pedido-1235",
"created_at": "2026-11-11T15:20:59.344Z",
"updated_at": "2026-11-11T15:20:59.345Z",
"amounts": {
"subtotal": 5990,
"discount": 0,
"total": 5990,
"paid": 0,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-11T15:20:59.344Z",
"expires_at": "2026-11-26T15:20:59.344Z",
"paid_at": null,
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Pedido 1235", "sku": null, "quantity": 1, "unit_price": 5990 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 12 }
},
"checkout": {
"redirect_url": null,
"cancel_url": null
},
"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_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",
"expires_at": "2026-11-11T16:20:59.344Z",
"end_to_end_id": null,
"payer": null
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": null
}Referência: Criar uma fatura
A rota é a de Criar uma fatura, com os mesmos campos e o bloco payment.
| Campo | Regra |
|---|---|
payment.method | pix. |
payment.pix.expires_in | Opcional: 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 customer | Obrigatório com payment: a fatura sem cliente só é paga pela página. |
Idempotency-Key | Cabeç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.
| Resultado | Tentativa | Resposta |
|---|---|---|
| QR Code emitido | pending, com o bloco pix | 201, com a fatura |
| Pix recusado na emissão | failed, com o motivo em failure | 201, com a fatura |
| A adquirente não respondeu a tempo | processing, sem o QR Code | 201, 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 aconteceu | Tentativa | Fatura | Evento |
|---|---|---|---|
| O Pix foi pago. | paid, com paid_at e o identificador da transação em pix.end_to_end_id | paid | invoice.paid |
| O QR Code venceu sem pagamento. | expired | pending | - |
billing.expires_at chegou sem pagamento. | como estava | expired | invoice.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ódigo | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
| - | 404 | Cliente não encontrado para o id informado. |
PZ100 | 422 | A soma dos itens é diferente do valor da fatura. |
PZ101 | 422 | Valor fora do limite desta conta. |
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.