PayZu PixReceber com Pix

Receber um Pix com QR Code


Nesta páginaEndpointHeadersBodyRespostaConfirmar o pagamentoErros

Crie a cobrança e mostre o QR Code ao pagador.

Endpoint

bash
POST https://pix.sandbox.payzu.dev/v1/pix

Referência: Criar uma cobrança Pix com QR Code

Headers

bash
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Body

json
{
  "amount": 10,
  "expiresIn": 600,
  "clientReference": "order_12345",
  "callbackUrl": "https://webhook.cool/",
  "generatedName": "John Doe",
  "generatedDocument": "12345678901",
  "generatedEmail": "john.doe@example.com"
}
CampoObrigatórioO que é
amountsimValor em reais, a partir de 1,00, com até duas casas decimais.
expiresInnãoValidade do QR Code em segundos inteiros, de 60 a 172.000.
clientReferencenãoO seu id do pedido. Repetir o mesmo valor retorna a mesma cobrança.
callbackUrlnãoOnde a PayZu avisa o pagamento.
generatedDocumentdependeCPF ou CNPJ do pagador. Obrigatório a partir do valor definido para a conta.
virtualAccountnãoSepara 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"
}
CampoComo usar
qrCodeTextMostre com um botão de copiar.
qrCodeBase64Para a imagem, use data:image/png;base64, seguido do valor.
qrCodeUrlNã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ódigoHTTPMensagem
PZD600400O valor mínimo do depósito é R$ 1,00.
PZD601400O valor máximo do depósito é R$ 50.000,00.
PZD602400Para depósitos acima de R$ 5.000,00 é obrigatório informar o documento.
PZD200422Depósito não permitido para esta conta.
PZD100424Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.
PZD103424O tempo limite de processamento do depósito foi atingido. Tente novamente.
PZD500424Nenhuma 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.