PayZu PixReceber com Pix
Receber um Pix com QR Code
Crie a cobrança e mostre o QR Code ao pagador.
Endpoint
bash
POST https://pix.sandbox.payzu.dev/v1/pixReferência: Criar uma cobrança Pix com QR Code
Headers
bash
Authorization: Bearer SEU_TOKEN
Content-Type: application/jsonBody
json
{
"amount": 10,
"expiresIn": 600,
"clientReference": "order_12345",
"callbackUrl": "https://webhook.cool/",
"generatedName": "John Doe",
"generatedDocument": "12345678901",
"generatedEmail": "john.doe@example.com"
}| Campo | Obrigatório | O que é |
|---|---|---|
amount | sim | Valor em reais, a partir de 1,00, com até duas casas decimais. |
expiresIn | não | Validade do QR Code em segundos inteiros, de 60 a 172.000. |
clientReference | não | O seu id do pedido. Repetir o mesmo valor retorna a mesma cobrança. |
callbackUrl | não | Onde a PayZu avisa o pagamento. |
generatedDocument | depende | CPF ou CNPJ do pagador. Obrigatório a partir do valor definido para a conta. |
virtualAccount | não | Separa lojas ou filiais na mesma conta. |
Resposta
json
{
"id": "PAYZU20260811R4TZ8WD1NC000000",
"status": "PENDING",
"amount": 10,
"qrCodeText": "00020126860014br.gov.bcb.pix2564qrcode.payzu.com.br/dynamic/11111111-2222-3333-4444-5555555555555204000053039865802BR5909PAYZUPLUS6009SAO PAULO62070503***630489B0",
"qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAAC...",
"qrCodeUrl": "https://pix.sandbox.payzu.dev/v1/pix/qr-code/PAYZU20260811R4TZ8WD1NC000000",
"clientReference": "order_12345",
"createdAt": "2026-08-11T21:59:11.579Z"
}| Campo | Como usar |
|---|---|
qrCodeText | Mostre com um botão de copiar. |
qrCodeBase64 | Para a imagem, use data:image/png;base64, seguido do valor. |
qrCodeUrl | Não entregue ao pagador: a rota exige o seu token. |
Confirmar o pagamento
O callbackUrl recebe a transação com status: "COMPLETED" quando o Pix é pago. Para conferir, consulte com GET /pix pelo id ou pelo clientReference.
Dê baixa pelo status, nunca só pela chegada do aviso.
A criação também gera um aviso nos webhooks da conta, com PENDING.
Se o Pix não for pago até o fim de expiresIn, o QR Code deixa de aceitar pagamento e a cobrança passa a EXPIRED quando a instituição informa a expiração. Uma cobrança já paga continua COMPLETED.
Erros
| Código | HTTP | Mensagem |
|---|---|---|
PZD600 | 400 | O valor mínimo do depósito é R$ 1,00. |
PZD601 | 400 | O valor máximo do depósito é R$ 50.000,00. |
PZD602 | 400 | Para depósitos acima de R$ 5.000,00 é obrigatório informar o documento. |
PZD200 | 422 | Depósito não permitido para esta conta. |
PZD100 | 424 | Não foi possível gerar o depósito junto à instituição financeira. Tente novamente. |
PZD103 | 424 | O tempo limite de processamento do depósito foi atingido. Tente novamente. |
PZD500 | 424 | Nenhuma instituição financeira disponível no momento. Tente novamente em instantes. |
Os códigos de autenticação e de validação estão no Catálogo de erros.