Crear retiro

Envía un Pix desde su saldo a la clave del beneficiario. El idEnvio es suyo, y repetir el mismo idEnvio con el mismo cuerpo devuelve el mismo retiro.

PUT /v2/ex/pix/{idEnvio}

Alcance: 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 }
}

Campos del request #

Campos del response #

Envíe un solo documento: favorecido.cpf o favorecido.cnpj. Los dos juntos responden 400 requisicao_invalida, y ninguno, o uno sin los dígitos verificadores, 400 documento_invalido. El beneficiario puede ser persona jurídica cuando capacidades.favorecidoPJ es true en GET /v2/ex/config; cuando es false, el favorecido.cnpj responde 400 favorecido_pj_nao_permitido, y la clave CNPJ con favorecido.cpf también. Cuando es true, la clave CNPJ con favorecido.cpf responde 400 chave_nao_pertence_ao_documento: declare el favorecido.cnpj del dueño de la clave. En el response y en las consultas, el beneficiario persona jurídica trae cnpj en lugar de cpf.

El documento puede ser opcional en su cuenta: vea documentoFavorecido.modo en GET /v2/ex/config. Con OPCIONAL, el retiro puede venir sin favorecido.cpf y sin favorecido.cnpj. En la clave CPF o CNPJ, el documento es la propia clave. En la clave de correo electrónico, teléfono o aleatoria, el retiro sale sin documento, y el favorecido de la respuesta trae solo la chave. Un favorecido.cpf o favorecido.cnpj que no es un documento válido se descarta, y el retiro sigue como si el campo no hubiera venido; el documento con puntuación que es válido sin ella vale, sin la puntuación. Cuando la cuenta por donde sale el retiro exige el documento, la respuesta es 422 documento_exigido_pela_nominal: envíe el documento y repita.

La regla de la clave es la misma para todas sus cuentas. Lea capacidades.saqueQualquerChave en GET /v2/ex/config. Cuando es true, la clave puede ser CPF, CNPJ, correo electrónico, teléfono con +55 o aleatoria; la clave CPF tiene que ser el favorecido.cpf y la clave CNPJ tiene que ser el favorecido.cnpj. La clave de correo electrónico, teléfono o aleatoria no se verifica contra el documento informado: verifíquela antes de enviar. La clave CNPJ con letra minúscula se lee en mayúscula. Cuando es false, la clave tiene que ser el propio documento del beneficiario, válido y sin puntuación, como en el ejemplo: el favorecido.cpf, con los 11 dígitos, o el favorecido.cnpj, donde capacidades.favorecidoPJ es true. La clave CPF o CNPJ de otro documento responde 400 chave_nao_pertence_ao_documento, la clave CNPJ donde capacidades.favorecidoPJ es false responde 400 favorecido_pj_nao_permitido, y correo electrónico, teléfono, aleatoria o documento sin los dígitos verificadores 422 chave_exige_documento. En los dos casos, el rechazo no crea el retiro.

Un retiro por encima del valor acordado, o a partir del tercero en el día al mismo beneficiario (el número también se puede acordar), o que supere la suma del día al mismo beneficiario, se crea con status igual a AGUARDANDO_APROVACAO y el objeto aprovacao (las regras y el expiraEm). El valor queda reservado y el retiro solo sale cuando un gestor de su empresa lo aprueba en el panel; sin decisión hasta aprovacao.expiraEm (24 horas, o el enviarAte cuando llega antes) termina NAO_REALIZADO y el valor vuelve. El evento es payout.aguardando_aprovacao, sin endToEndId: se genera de nuevo en la aprobación, así que use siempre el idEnvio. Lo mismo sucede con el retiro que usted envía con exigirAprovacao igual a true, incluso por debajo de esas reglas: aprovacao.regras trae PEDIDA primero, junto con las otras que el retiro dispare. Un nombre parecido e incorrecto, como exigeAprovacao, responde 400 campo_desconhecido; verifique en el response el status y el eco exigirAprovacao, y pruebe el primero con R$ 1,00.

El gestor aprueba o rechaza. aprovacao.desfecho es APROVADO, RECUSADO, EXPIRADO o CANCELADO, y aprovacao.regras trae PEDIDA, VALOR, QUANTIDADE_DESTINO o SOMA_DESTINO. Fuera del aprobado, el retiro termina NAO_REALIZADO con motivo.codigo MS02 (su empresa lo rechazó) o MS03 (plazo vencido o cancelado por nosotros), clase TERMINAL.

Con validadeSegundos, el envío no comienza después de enviarAte, y el retiro que no salió termina NAO_REALIZADO con el motivo MS03 y el valor vuelve. El envío que comenzó antes puede llegar a la institución después, y el retiro que ella aceptó sigue hasta su desenlace. Si el envío quedó sin respuesta, verificamos con la institución antes de cerrar, algunos minutos después de enviarAte. Espere el evento, y no el horario. Repetir el mismo idEnvio devuelve el enviarAte de la primera llamada, pero el mismo idEnvio con y sin validadeSegundos responde 409 id_envio_duplicado. Un nombre parecido e incorrecto, como expiration, responde 400 campo_desconhecido.

Algunas cuentas no envían Pix. Lea capacidades.saque en GET /v2/ex/config (con ?subconta= cuando el retiro sale de una subcuenta): cuando es false, el retiro responde 503 capacidade_indisponivel y no se crea.

El retiro reserva el valor más la tarifa, que usted ve en el panel. Por eso un retiro igual al disponivel completo responde 422 saldo_insuficiente. Para retirar todo, envíe el saqueMaximo de Saldo: es el mayor valor que cabe con la tarifa, hasta el centavo.

Algunas cuentas tienen un valor máximo por Pix de retiro. Por encima de él el retiro responde 422 valor_acima_do_maximo, con el máximo en detail, y no se crea. En esas cuentas el saqueMaximo no pasa de ese máximo, y el resto sale en otro retiro.

El desenlace llega por el webhook payout.realizado o payout.nao_realizado. Después de un timeout o 5xx, consulte GET /v2/ex/pix/{idEnvio} antes de repetir; si responde 404, repita el PUT con el mismo idEnvio.

Errores #