创建提现

从您的余额向收款人的 Pix 密钥发送一笔 Pix。idEnvio 由您生成，用相同的正文重复同一个 idEnvio 会返回同一笔提现。

PUT /v2/ex/pix/{idEnvio}

权限范围：ex.pix.send。

PUT /v2/ex/pix/SAQ01J1ZK7M9QW3ERT5TY6UI8O
{
  "tipo": "SAQUE",
  "valor": "300.00",
  "solicitadoEm": "2026-09-18T12:00:00Z",
  "favorecido": { "chave": "12345678909", "cpf": "12345678909" },
  "referenciaExterna": "saque-778812",
  "infoPagador": "Saque pedido 778812"
}
→ 201
{
  "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",
  "sla": { "estouradoNaEntrada": false, "restanteSegundos": 7199 }
}

请求字段 #

响应字段 #

只发送一种证件号：favorecido.cpf 或 favorecido.cnpj。两者同时发送返回 400 requisicao_invalida；都不发送，或证件号的校验位无效，返回 400 documento_invalido。当 GET /v2/ex/config 中 capacidades.favorecidoPJ 为 true 时，收款人可以是企业；为 false 时，favorecido.cnpj 返回 400 favorecido_pj_nao_permitido，CNPJ 密钥搭配 favorecido.cpf 也是如此。为 true 时，CNPJ 密钥搭配 favorecido.cpf 返回 400 chave_nao_pertence_ao_documento：请填写该密钥所有者的 favorecido.cnpj。在响应和查询中，企业收款人返回 cnpj 代替 cpf。

您的账户可以将证件设为可选：见 GET /v2/ex/config 中的 documentoFavorecido.modo。为 OPCIONAL 时，提现可以不带 favorecido.cpf，也不带 favorecido.cnpj。CPF 或 CNPJ 密钥的证件即为密钥本身。电子邮件、电话或随机密钥的提现不带证件发出，响应中的 favorecido 只有 chave。不是有效证件的 favorecido.cpf 或 favorecido.cnpj 会被丢弃，提现按未发送该字段的情况继续；带标点、去掉标点后有效的证件按去掉标点后的形式使用。当提现经由的账户要求证件时，响应为 422 documento_exigido_pela_nominal：请发送证件后重试。

您所有账户的密钥规则都相同。请读取 GET /v2/ex/config 中的 capacidades.saqueQualquerChave。为 true 时，密钥可以是 CPF、CNPJ、电子邮件、带 +55 的电话号码或随机密钥；CPF 密钥必须是 favorecido.cpf，CNPJ 密钥必须是 favorecido.cnpj。电子邮件、电话或随机密钥不会与所填的证件号核对：发送前请自行确认。含小写字母的 CNPJ 密钥按大写读取。为 false 时，密钥必须是收款人本人的证件号，有效且不带标点，如示例所示：11 位数字的 favorecido.cpf，或在 capacidades.favorecidoPJ 为 true 时的 favorecido.cnpj。其他证件号的 CPF 或 CNPJ 密钥返回 400 chave_nao_pertence_ao_documento，在 capacidades.favorecidoPJ 为 false 时 CNPJ 密钥返回 400 favorecido_pj_nao_permitido，电子邮件、电话、随机密钥或校验位无效的证件号返回 422 chave_exige_documento。两种情况下，被拒绝时都不会创建提现。

金额超过约定值的提现、当天向同一收款人发起的第三笔及以后的提现（次数也可约定），或超过当天向同一收款人累计金额的提现，会以 status 为 AGUARDANDO_APROVACAO 创建，并带有 aprovacao 对象（regras 和 expiraEm）。金额会被预留，只有贵公司的管理员在控制台批准后，提现才会发出；若在 aprovacao.expiraEm（24 小时，若 enviarAte 更早则以其为准）之前没有作出决定，提现以 NAO_REALIZADO 结束，金额退回。事件为 payout.aguardando_aprovacao，不带 endToEndId：它在批准时重新生成，因此请始终使用 idEnvio。您发送 exigirAprovacao 为 true 的提现也是如此，即使它低于这些规则：aprovacao.regras 中 PEDIDA 排在最前，后面是该提现触发的其他规则。名称相近但错误的字段，例如 exigeAprovacao，返回 400 campo_desconhecido；请在响应中核对 status 和回显的 exigirAprovacao，并先用 R$ 1,00 验证第一笔。

管理员可以批准或拒绝。aprovacao.desfecho 为 APROVADO、RECUSADO、EXPIRADO 或 CANCELADO，aprovacao.regras 包含 PEDIDA、VALOR、QUANTIDADE_DESTINO 或 SOMA_DESTINO。除批准外，提现都以 NAO_REALIZADO 结束，motivo.codigo 为 MS02（贵公司拒绝）或 MS03（期限已过或被我们取消），类别为 TERMINAL。

使用 validadeSegundos 时，enviarAte 之后不会再开始发送，没有发出的提现以 NAO_REALIZADO 结束，原因为 MS03，金额退回。在此之前开始的发送可能晚于该时间才到达机构，机构已接受的提现会继续进行，直到机构给出结果。如果发送没有收到响应，我们会在 enviarAte 之后几分钟向机构确认，然后再结束。请等待事件，而不是看时间。重复同一个 idEnvio 会返回首次调用的 enviarAte，但同一个 idEnvio 一次带、一次不带 validadeSegundos 会返回 409 id_envio_duplicado。名称相近但错误的字段，例如 expiration，返回 400 campo_desconhecido。

有些账户不能发送 Pix。请读取 GET /v2/ex/config 中的 capacidades.saque（从子账户提现时带 ?subconta=）：为 false 时，提现返回 503 capacidade_indisponivel，且不会创建。

提现会预留金额加手续费，手续费可在控制台查看。因此，金额等于全部 disponivel 的提现会返回 422 saldo_insuficiente。要全部提现，请发送余额中的 saqueMaximo：这是计入手续费后能容纳的最大金额，精确到分。

有些账户对每笔提现 Pix 设有最高金额。超过该金额的提现返回 422 valor_acima_do_maximo，最高金额在 detail 中返回，且不会创建。在这些账户中，saqueMaximo 不会超过该最高金额，其余部分通过另一笔提现发出。

结果通过 webhook payout.realizado 或 payout.nao_realizado 送达。超时或出现 5xx 后，请先查询 GET /v2/ex/pix/{idEnvio} 再重试；如果返回 404，请用同一个 idEnvio 重复 PUT。

错误 #