Consultar retiro

Devuelve el retiro por el idEnvio, con el estado actual.

GET /v2/ex/pix/{idEnvio}

Alcance: ex.pix.send.read.

GET /v2/ex/pix/SAQ01J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000003",
  "status": "EM_PROCESSAMENTO",
  "tipo": "SAQUE",
  "valor": "300.00",
  "solicitadoEm": "2026-09-18T12:00:00Z",
  "prazoRegulatorio": "2026-09-18T14:00:00Z",
  "favorecido": { "chave": "12345678909", "cpf": "12345678909" },
  "referenciaExterna": "saque-778812",
  "infoPagador": "Saque pedido 778812",
  "origem": "API",
  "sla": { "estouradoNaEntrada": false, "restanteSegundos": 7199 }
}

origem es API cuando el retiro vino de su integración, PAINEL cuando alguien de su equipo lo envió por el panel, a un beneficiario registrado, y BACKOFFICE cuando la institución lo hizo a su pedido. En PAINEL, origemLogin trae el login de quien lo envió.

Un envío por el panel, o de la institución, por encima del valor máximo de cada Pix llega como varios retiros de valores iguales, con 2 segundos entre ellos. El primero lleva el idEnvio del envío, y los demás el mismo idEnvio con P002, P003 y así sucesivamente al final. Cada uno tiene su endToEndId, su tarifa y sus avisos de webhook. Los retiros que su integración crea no se dividen en varios retiros.

Cuando el Pix expira por tiempo en el SPI (código AB03: el banco de quien recibe no respondió a tiempo, y el Pix no salió), en algunas cuentas el retiro no termina en el acto. Se envía de nuevo algunas veces, con una espera que se duplica en cada intento, y sigue EM_PROCESSAMENTO mientras tanto. Cada intento tiene otro endToEndId: vale el del aviso payout.realizado, y la consulta por el endToEndId de un intento anterior también devuelve el retiro. El aviso payout.nao_realizado con AB03 solo llega después del último intento. Lo mismo ocurre, en algunas cuentas, cuando la institución de pago rechaza el envío por un motivo pasajero: el retiro se envía de nuevo de la misma forma, y el aviso payout.nao_realizado (con MS03) solo llega después del último intento. Cuando responde que está indisponible, el retiro espera: se envía de nuevo una vez, algunos minutos después o cuando vuelve, y el aviso payout.nao_realizado (con MS03) llega si se rechaza de nuevo, o si no vuelve a tiempo. Y cuando rechaza por falta de saldo, en su propia cuenta o en el banco por el que envía el Pix, el retiro espera el saldo: se envía de nuevo cada minuto, y el aviso payout.nao_realizado con AM04 solo llega si el saldo no vuelve a tiempo.

Cuando hay más de una cuenta para sus retiros, el retiro que la institución rechaza se envía por la siguiente antes de volver como no realizado, con el mismo idEnvio y otro endToEndId, y sigue EM_PROCESSAMENTO mientras tanto. El aviso payout.nao_realizado solo llega después de todas, con el motivo de la última.

Todos estos nuevos intentos, incluido el paso a otra cuenta, ocurren solo en los primeros minutos después de que el retiro llega. Pasado ese plazo, el rechazo termina el retiro, y el aviso payout.nao_realizado llega en el acto.

En algunas cuentas la institución divide el retiro por encima de un límite en varios Pix iguales, uno después del otro. Para su integración sigue siendo un solo retiro, con el idEnvio, el valor y los avisos de siempre, y el endToEndId del retiro es el del primer Pix. Solo en ese retiro la respuesta trae valorRealizado y pix:

Para saber cuánto llegó al beneficiario, lea valorRealizado, y no solo status y valor. Si el primer Pix no sale, el retiro termina NAO_REALIZADO con su motivo, como un retiro común. La consulta por cualquier endToEndId de pix devuelve el retiro.

La tarifa se cobra por Pix, sobre el valor de cada uno: el saldo disponible debe cubrir el valor del retiro y una tarifa por Pix, y el extracto trae una línea de tarifa por cada Pix. Cuando la institución acordó con usted una sola tarifa por retiro, el retiro paga la tarifa de un retiro sobre el valor que salió, repartida entre los Pix: con tarifa fija el primer Pix la paga y los demás no tienen línea de tarifa en el extracto.

Un retiro que esperó aprobación trae aprovacao (regras, expiraEm y, una vez decidido, desfecho, decididaEm, decididaPor y motivo), y la solicitud con exigirAprovacao trae el eco exigirAprovacao igual a true. Mientras espera, y si no es aprobado, no trae endToEndId. Cuando la institución lo aprueba a su pedido, o cancela el retiro, decididaPor viene instituicao, con el motivo. El retiro creado con validadeSegundos trae enviarAte, el plazo para salir.

El beneficiario persona jurídica viene con cnpj en lugar de cpf. Acepte los dos al leer, aunque su integración solo envíe CPF: un retiro enviado por el panel puede ser para una persona jurídica.

Un retiro liquidado trae liquidadoEm y sla.cumprido:

{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "status": "REALIZADO",
  "liquidadoEm": "2026-09-18T12:00:09Z",
  "sla": { "cumprido": true, "estouradoNaEntrada": false }
}

Cuando la institución que envía el Pix informa quién lo recibió, el retiro liquidado trae recebedor, con nome, documento, ispb, banco (el nombre de la institución de quien recibió), bancoNomeCompleto, bancoCodigo (el código de tres dígitos del banco, como 260), bancoCnpj (el CNPJ de la institución, sin máscara), agencia, conta y tipoConta. El nombre, el código y el CNPJ vienen de las listas de participantes del Banco Central de Brasil, y cuando la institución informa solo el nombre del banco, el ispb se obtiene de la lista por el nombre. Cualquier campo puede faltar, y el documento puede venir con parte de los dígitos ocultos. Sin esa información el campo no viene: nunca es el beneficiario del pedido.

El banco del beneficiario puede devolver un retiro ya realizado, en todo o en parte. El retiro sigue REALIZADO, con su valor, y pasa a traer valorDevolvido, la suma de lo que volvió. Cada devolución llega por el evento payout.devolucao_recebida y entra en el extracto como una línea DEVOLUCAO_DE_SAQUE.

La consulta trae también devolucoes, una línea por devolución, de la más antigua a la más nueva:

La tarifa del retiro no vuelve. El listado no trae devolucoes: trae valorDevolvido.

El retiro liquidado trae tarifa, la tarifa que pagó, la misma de la línea TARIFA del extracto. Se cobra en la liquidación: el retiro en curso, el no realizado y el de tarifa cero no la traen.

Un retiro NAO_REALIZADO trae motivo con codigo, classe y descricao:

GET /v2/ex/pix/SAQ02J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "idEnvio": "SAQ02J1ZK7M9QW3ERT5TY6UI8O",
  "status": "NAO_REALIZADO",
  "tipo": "SAQUE",
  "valor": "20.00",
  "liquidadoEm": "2026-09-18T11:00:09Z",
  "motivo": {
    "codigo": "AC03",
    "classe": "CORRIGIVEL",
    "descricao": "Agência/conta do usuário recebedor inexistente ou inválida."
  }
}

classe es CORRIGIVEL cuando otra clave o cuenta lo resuelve, RETRYAVEL cuando la misma solicitud puede pasar más tarde y TERMINAL cuando no se repite.

descricao es una frase corta para quien atiende a su cliente, escrita por nosotros: el significado del código, o la causa cuando el código no basta. Decida por el codigo y por la classe, nunca por la frase. Puede faltar en un retiro antiguo.

MS03 es el rechazo sin un motivo que podamos transmitir: la institución que envía el Pix lo rechazó sin código, el plazo de enviarAte venció, la aprobación expiró o fue cancelada, soporte desistió de un retiro que no salió, el valor está por encima del máximo por Pix de retiro de la cuenta y el retiro no salió, o la cuenta pasó a enviar solo a la clave que es el documento del beneficiario y el retiro, a otra clave, aún no había sido enviado. No se repite con el mismo idEnvio; se puede intentar con un nuevo idEnvio. Cuando la descricao indica el máximo por Pix, el nuevo retiro va en Pix de hasta ese máximo: por encima de él responde 422 valor_acima_do_maximo. Cuando la descricao indica que la cuenta solo envía a la clave que es el CPF o el CNPJ del beneficiario, el nuevo retiro va a esa clave: otra responde 422 chave_exige_documento. MS02 es el rechazo de su empresa en la aprobación.

Línea de tiempo #

GET /v2/ex/pix/{idEnvio}?historico=true trae historico, la línea de tiempo del retiro, con el aviso de cada paso a su webhook. Un valor que no sea true o false responde 400 filtro_invalido.

historico.passos viene en el orden del tiempo. Cada paso tiene passo y em y, según el paso, valor, rtrId, parte, motivo y tipo:

El paso que generó un aviso a su webhook trae aviso:

Con historico.avisosApurados en falso, los avisos no se leyeron ahora, y los pasos vienen sin aviso.

Reenviar el aviso de un paso #

POST /v2/ex/pix/{idEnvio}/avisos/{eventoId}/reenvio

Alcance: ex.webhook.write. Sin cuerpo.

Envía de nuevo a su webhook el aviso de un paso con reenviavel igual a true. Responde 202 con idReenvio y eventoId, y el pedido aparece en la lista de los reenvíos del webhook.

Por el endToEndId #

GET /v2/ex/pix/e2e/{e2eId}

GET /v2/ex/pix/e2e/E12345678202609181200000000000003
→ 200
{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000003",
  "status": "EM_PROCESSAMENTO"
}

Comprobante #

GET /v2/ex/comprovantes/{idEnvio} devuelve el comprobante en PDF de un retiro REALIZADO. Antes del desenlace, y en el retiro NAO_REALIZADO, responde 422 saque_nao_liquidado.

En el retiro dividido en varios Pix, el comprobante trae el valor que salió y la lista de los Pix, con el valor, la situación y el endToEndId de cada Pix realizado. Cuando salió menos que lo pedido, también indica el valor pedido y lo que volvió al saldo.

Errores #