查询提现

按 idEnvio 返回提现及其当前状态。

GET /v2/ex/pix/{idEnvio}

权限范围：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 为 API；您团队中有人通过控制台向已登记的收款人发送时，为 PAINEL；机构应您的要求代为发起时，为 BACKOFFICE。为 PAINEL 时，origemLogin 返回发送人的登录名。

通过控制台或由机构发起、超过每笔 Pix 最高金额的发送，会以多笔金额相同的提现到达，彼此间隔 2 秒。第一笔使用该次发送的 idEnvio，其余几笔使用同一个 idEnvio，末尾加上 P002、P003，依此类推。每笔都有自己的 endToEndId、自己的手续费和自己的 webhook 通知。您的集成创建的提现不会拆分为多笔提现。

当 Pix 在 SPI 中超时（代码 AB03：收款方银行未及时响应，Pix 未发出）时，在部分账户中提现不会立即结束。系统会重新发送几次，每次尝试的等待时间翻倍，期间保持 EM_PROCESSAMENTO。每次尝试的 endToEndId 都不同：以 payout.realizado 通知中的为准，用之前某次尝试的 endToEndId 查询也会返回该提现。带 AB03 的 payout.nao_realizado 通知只会在最后一次尝试之后发出。在部分账户中，当支付机构因暂时性原因拒绝发送时，也会这样处理：提现会以同样的方式重新发送，带 MS03 的 payout.nao_realizado 通知只会在最后一次尝试之后发出。当支付机构回复其暂时不可用时，提现会等待：在几分钟后或其恢复时重新发送一次；如果再次被拒绝，或未能及时恢复，会发出带 MS03 的 payout.nao_realizado 通知。当支付机构因其自身账户或其发送 Pix 所经银行的余额不足而拒绝时，提现会等待余额：每分钟重新发送一次，只有在余额未能及时恢复时，才会发出带 AM04 的 payout.nao_realizado 通知。

当您的提现有多个账户可用时，被机构拒绝的提现会先通过下一个账户发送，然后才会以未完成返回，idEnvio 不变，endToEndId 不同，期间保持 EM_PROCESSAMENTO。payout.nao_realizado 通知只会在所有账户都尝试之后发出，带最后一个账户的原因。

所有这些重新尝试，包括转到另一个账户，都只在提现到达后的最初几分钟内进行。超过这个期限后，拒绝会结束该提现，payout.nao_realizado 通知会立即发出。

在部分账户中，机构会把超过某一限额的提现拆分为多笔金额相同的 Pix，依次发出。对您的集成而言，它仍是一笔提现，idEnvio、valor 和通知与往常一样，提现的 endToEndId 即第一笔 Pix 的那一个。只有这类提现的响应才带有 valorRealizado 和 pix：

要知道收款人实际收到多少，请读取 valorRealizado，而不只是 status 和 valor。如果第一笔 Pix 未发出，提现以 NAO_REALIZADO 结束并带有该 Pix 的 motivo，与普通提现相同。按 pix 中任一 endToEndId 查询都会返回该提现。

费用按每笔 Pix 收取，以每笔的金额计算：可用余额须覆盖提现金额加上每笔 Pix 一笔费用，对账单中每笔 Pix 各有一行费用。如果机构与您约定每笔提现只收一笔费用，则该提现按实际转出的金额支付一笔提现的费用，并在各笔 Pix 之间分摊：固定费用由第一笔 Pix 支付，其余几笔在对账单中没有费用行。

等待过审批的提现带有 aprovacao（regras、expiraEm，作出决定后还有 desfecho、decididaEm、decididaPor 和 motivo），带 exigirAprovacao 的请求会回显 exigirAprovacao 为 true。等待期间以及未获批准时，不返回 endToEndId。机构应您的要求批准或取消提现时，decididaPor 为 instituicao，并附带 motivo。使用 validadeSegundos 创建的提现带有 enviarAte，即发出的期限。

企业收款人返回 cnpj 代替 cpf。读取时请同时接受两者，即使您的集成只发送 CPF：通过控制台发送的提现可能是付给企业的。

已结算的提现带有 liquidadoEm 和 sla.cumprido：

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

当发送 Pix 的机构告知收款人时，已结算的提现带有 recebedor，包含 nome、documento、ispb、banco（收款人所在机构的名称）、bancoNomeCompleto、bancoCodigo（银行的三位代码，例如 260）、bancoCnpj（机构的 CNPJ，不带格式）、agencia、conta 和 tipoConta。名称、代码和 CNPJ 来自巴西中央银行的参与者名单；当机构只告知银行名称时，ispb 按名称从名单中取得。任何字段都可能缺失，证件号码可能隐藏部分数字。没有该信息时不返回此字段：它绝不是请求中的收款人。

收款人的银行可能全部或部分退回一笔已完成的提现。提现仍为 REALIZADO，金额不变，并新增 valorDevolvido，即退回金额的总和。每次退回都通过事件 payout.devolucao_recebida 送达，并作为一行 DEVOLUCAO_DE_SAQUE 计入对账单。

查询还会返回 devolucoes，每次退回一行，从最早到最新：

提现手续费不退回。列表不返回 devolucoes，只返回 valorDevolvido。

已结算的提现带有 tarifa，即该笔提现支付的费用，与对账单中 TARIFA 行的金额相同。费用在结算时收取：处理中的提现、未完成的提现以及零费用的提现不带此字段。

NAO_REALIZADO 的提现带有 motivo，包含 codigo、classe 和 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 为 CORRIGIVEL 表示换一个密钥或账户可以解决，为 RETRYAVEL 表示同一请求稍后可能成功，为 TERMINAL 表示不应重试。

descricao 是我们为服务您客户的人员撰写的一句简短说明：代码的含义，或在代码不足以说明时给出原因。请依据 codigo 和 classe 作判断，切勿依据这句话。旧的提现中可能没有它。

MS03 表示无法向您转述具体原因的拒绝：发送 Pix 的机构未给出代码就拒绝了，enviarAte 的期限已过，审批已过期或被取消，支持团队放弃了一笔未发出的提现，金额高于该账户每笔提现 Pix 的最高金额且提现未发出，或该账户改为只向即为收款人证件号的密钥发送，而这笔发往其他密钥的提现尚未发出。不要用同一个 idEnvio 重试；可以尝试新的 idEnvio。当 descricao 说明了每笔 Pix 的最高金额时，新的提现按不超过该金额的 Pix 发出：超过该金额返回 422 valor_acima_do_maximo。当 descricao 说明该账户只向即为收款人 CPF 或 CNPJ 的密钥发送时，新的提现发往该密钥：其他密钥返回 422 chave_exige_documento。MS02 表示贵公司在审批中拒绝。

时间线 #

GET /v2/ex/pix/{idEnvio}?historico=true 返回 historico，即提现的时间线，以及每一步发往您 webhook 的通知。取值不是 true 或 false 时返回 400 filtro_invalido。

historico.passos 按时间顺序排列。每一步包含 passo 和 em，并根据步骤带有 valor、rtrId、parte、motivo 和 tipo：

产生了发往您 webhook 通知的步骤带有 aviso：

historico.avisosApurados 为 false 时，表示此次未读取到通知，各步骤不带 aviso。

重新发送某一步的通知 #

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

权限范围：ex.webhook.write。无请求体。

将 reenviavel 为 true 的步骤通知再次发送到您的 webhook。返回 202，带 idReenvio 和 eventoId，该请求会出现在 webhook 重新发送的列表中。

按 endToEndId 查询 #

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

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

回单 #

GET /v2/ex/comprovantes/{idEnvio} 返回 REALIZADO 提现的 PDF 回单。在有结果之前，以及对 NAO_REALIZADO 的提现，返回 422 saque_nao_liquidado。

对于拆分为多笔 Pix 的提现，回单显示实际发出的金额和各笔 Pix 的列表，包括每笔已完成 Pix 的金额、状态和 endToEndId。发出金额少于请求金额时，回单还会写明请求金额以及退回余额的部分。

错误 #