Referência da API

Saque por QR Code

Paga um QR Code PIX (string BR Code copia-e-cola). Use para pagar boletos PIX, cobranças dinâmicas e qualquer QR Code gerado por terceiro.

POST/withdraws/cash-out/qrc

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

copyAndPastestringobrigatório

A string BR Code completa, copia-e-cola, a ser paga.

Exemplo: 00020126580014br.gov.bcb.pix...6304B0D2

amountnumberobrigatório

Valor em centavos. Para QR Codes estáticos com valor definido, isso precisa bater exatamente. Para QR Codes sem valor, esse é o valor que você decide pagar.

Exemplo: 10000

externalIdstringopcional

Sua referência para esse pagamento.

Exemplo: pagamento-boleto-456

postbackUrlstringopcional

URL de webhook para eventos desse saque.

Exemplo: https://seu-dominio.com/webhook

Body da requisição

Content-Type: application/json

JSON

{
  "copyAndPaste": "00020126580014br.gov.bcb.pix013636c1b4d1-65a0-4c77-9b7a-1234567890ab5204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***6304B0D2",
  "amount": 10000,
  "externalId": "pagamento-boleto-456"
}

Respostas

201

Saque aceito. Os campos do recebedor vêm vazios na resposta síncrona — são preenchidos quando o SPI confirma a transferência e chegam no webhook resultante.

JSON

{
  "id": "withdraw-id-1234",
  "externalId": "pagamento-boleto-456",
  "status": "WITHDRAW_REQUEST",
  "amount": 10000,
  "totalAmount": 10050,
  "institution": "",
  "receiverPix": "00020126580014br.gov.bcb.pix...6304B0D2",
  "receiverName": "",
  "receiverDocument": "",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "createdAt": "2026-04-08T15:00:00.000Z"
}

400

BR Code inválido, expirado, ou o valor declarado nele não bate com amount.

JSON

{
  "statusCode": 400,
  "message": "Invalid BR Code"
}

401

API key inválida ou ausente.

JSON

{ "statusCode": 401, "message": "Unauthorized" }

Exemplos

cURL

curl -X POST "https://api.pagnovo.com/withdraws/cash-out/qrc" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "copyAndPaste": "00020126580014br.gov.bcb.pix...6304B0D2",
    "amount": 10000,
    "externalId": "pagamento-boleto-456"
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch("https://api.pagnovo.com/withdraws/cash-out/qrc", {
  method: "POST",
  headers: {
    Authorization: `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    copyAndPaste: brCode,
    amount: 10000,
    externalId: "pagamento-boleto-456",
  }),
});

const w = await res.json();
console.log(w.id, w.status);