Buscar saque

Retorna o estado completo de um saque: status, timestamps para cada evento do ciclo de vida, dados do destinatário, custos e a URL do comprovante. Busque por ID interno, seu `externalId` ou o `end2End` do PIX.

GET/withdraws/collect/:withdrawId

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

withdrawIdstring (path)obrigatório

O valor a buscar. ID interno, externalId ou end2End — escolhido pelo `searchBy`.

Exemplo: withdraw-id-1234

searchBy'id' | 'externalId' | 'end2End'opcional

Qual campo usar na busca. Padrão `id`.

Exemplo: externalId

Respostas

200

Saque encontrado. Os timestamps opcionais te dizem o ciclo de vida: approvedAt preenchido significa que o SPI confirmou; rejectedAt preenchido significa que falhou; returnedAt preenchido significa que voltou.

Enquanto o status estiver em WITHDRAW_REQUEST ou WITHDRAW_PROCESSING, não dispare um novo saque — aguarde o estado final chegar via webhook ou consulta.

JSON

{
  "id": "withdraw-id-1234",
  "createdAt": "2026-04-08T15:00:00.000Z",
  "approvedAt": "2026-04-08T15:00:12.451Z",
  "rejectedAt": null,
  "returnedAt": null,
  "institution": "ITAÚ UNIBANCO",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "receiverPix": "maria@exemplo.com",
  "totalAmount": 10050,
  "amount": 10000,
  "costTax": 25,
  "costFee": 25,
  "status": "WITHDRAW_APPROVED",
  "externalId": "saque-789",
  "end2End": "E98765432202604081500123456789012",
  "errorMessage": null,
  "voucher": "https://voucher.pagnovo.com/receipt?token=..."
}

400

Valor inválido em searchBy.

JSON

{
  "statusCode": 400,
  "message": "Invalid searchBy value"
}

404

Saque não encontrado.

JSON

{
  "statusCode": 404,
  "message": "Withdraw not found"
}

Exemplos

cURL

# Por ID interno
curl -X GET "https://api.pagnovo.com/withdraws/collect/withdraw-id-1234" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

# Pelo seu externalId
curl -X GET "https://api.pagnovo.com/withdraws/collect/saque-789?searchBy=externalId" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

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

const res = await fetch(
  "https://api.pagnovo.com/withdraws/collect/saque-789?searchBy=externalId",
  { headers: { Authorization: `Basic ${token}` } },
);

if (res.status === 404) {
  console.log("não encontrado");
  return;
}

const w = await res.json();

if (w.status === "WITHDRAW_REQUEST" || w.status === "WITHDRAW_PROCESSING") {
  // Ainda em curso. Aguarde o webhook final antes de qualquer retry.
  console.log("em curso, status:", w.status);
  return;
}

if (w.status === "WITHDRAW_APPROVED") {
  console.log("aprovado em:", w.approvedAt);
  console.log("E2E:", w.end2End);
  console.log("comprovante:", w.voucher);
}