Pagar um Pix copia e cola
Quite com o saldo da conta um código Pix copia e cola, estático ou dinâmico. Valem os limites e o teto diário do saque, com a tarifa própria que aparece em Consultar os limites e as tarifas.
Antes de pagar
Descubra se o código é dinâmico e se fixa o valor.
2. Consultar o recebedorMostre o nome do titular e o valor ao usuário antes de confirmar.
Pague o código
brCode: o código exatamente como o usuário colou.Idempotency-Key: uma nova por pagamento.amount: obrigatório quando o código não fixa o valor. No código dinâmico, mande também quando o código fixar o valor, com o valor que o usuário conferiu na consulta do recebedor.comment: o texto que o recebedor vai ver.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/pix/qr-payments' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--header 'Content-Type: application/json' \
--data '{
"brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572",
"comment": "Pedido 4821"
}'{
"id": "P20261005114011H2P6XG8VNMC127431",
"status": "PROCESSING",
"amount": 2500,
"serviceFee": 100,
"totalDebited": 2600,
"pixKey": "f***@exemplo.com",
"bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999" },
"comment": "Pedido 4821",
"endToEndId": null,
"failureReason": null,
"callbackUrl": null,
"createdAt": "2026-10-05T14:40:11.002Z",
"confirmedAt": null
}Referência: Pagar um Pix copia e cola
O valor de um código dinâmico pode mudar depois da leitura.
Um valor diferente no pagamento é recusado, sem débito.
Para repetir, use a mesma Idempotency-Key e o mesmo código; trocar o código mantendo a chave dá 409. A cota, de 5 por minuto por credencial e 10 por conta, é a mesma do saque e da devolução.
Confirme a entrega
Dê o pagamento como feito só quando chegar WITHDRAW_COMPLETED. Os avisos são os do saque, com operation igual a EXTERNAL_PAYMENT, e os corpos estão em Saque criado, Saque concluído e Saque falhou.
Para conferir, use Consultar um saque ou pagamento. Com o pagamento CONFIRMED, o PDF sai em Comprovante do saque.
O pagamento não tem externalRef.
Guarde o id da resposta com o seu pedido para casar os avisos: ele é o mesmo withdrawId dos webhooks.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
QR_CRC | 400 | O código PIX está corrompido — copie novamente do recebedor. |
QR_MALFORMED | 400 | Este código PIX não está num formato válido. |
QR_NOT_PIX | 400 | Este código não é um QR code de PIX. |
WITHDRAW_DISABLED | 403 | Saque desabilitado para esta conta. |
PIX_DEST_PIX_KEY | 404 | Não encontramos essa chave PIX. Confira se ela está correta. |
QR_AMOUNT_DISAGREES | 422 | O valor impresso no QR code é diferente do que o banco do recebedor informa. Confirme o valor com quem cobrou. |
QR_AMOUNT_MISMATCH | 422 | O valor deste QR code é diferente do que foi informado. Se o código é dinâmico, quem cobrou pode tê-lo alterado depois da leitura — leia o código de novo. |
QR_AMOUNT_REQUIRED | 422 | Este QR code não fixa valor — informe quanto pagar. |
WITHDRAW_ABOVE_TICKET_MAX | 422 | O valor excede o máximo permitido para saque. |
WITHDRAW_BELOW_TICKET_MIN | 422 | O valor é inferior ao mínimo permitido para saque. |
WITHDRAW_DAILY_LIMIT | 422 | O limite diário de saque desta conta foi atingido. |
WITHDRAW_INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para este saque. |
WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE | 422 | O saldo desta conta não cobre este saque agora. |
WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER | 422 | A chave PIX de destino foi recusada. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.