Criar saque

Envia um Pix do seu saldo para a chave do favorecido. O idEnvio é seu, e repetir o mesmo idEnvio com o mesmo corpo devolve o mesmo saque.

PUT /v2/ex/pix/{idEnvio}

Escopo: 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 do request #

Campos do response #

Mande um documento só: favorecido.cpf ou favorecido.cnpj. Os dois juntos respondem 400 requisicao_invalida, e nenhum, ou um sem os dígitos verificadores, 400 documento_invalido. O favorecido pode ser pessoa jurídica quando capacidades.favorecidoPJ é true em GET /v2/ex/config; quando é false, o favorecido.cnpj responde 400 favorecido_pj_nao_permitido, e a chave CNPJ com favorecido.cpf também. Quando é true, a chave CNPJ com favorecido.cpf responde 400 chave_nao_pertence_ao_documento: declare o favorecido.cnpj do dono da chave. No response e nas consultas, o favorecido pessoa jurídica traz cnpj no lugar de cpf.

O documento pode ser opcional na sua conta: veja documentoFavorecido.modo em GET /v2/ex/config. Com OPCIONAL, o saque pode vir sem favorecido.cpf e sem favorecido.cnpj. Na chave CPF ou CNPJ, o documento é a própria chave. Na chave de e-mail, telefone ou aleatória, o saque sai sem documento, e o favorecido da resposta traz só a chave. Um favorecido.cpf ou favorecido.cnpj que não é um documento válido é descartado, e o saque segue como se o campo não tivesse vindo; o documento com pontuação que é válido sem ela vale, sem a pontuação. Quando a conta por onde o saque sai exige o documento, a resposta é 422 documento_exigido_pela_nominal: mande o documento e repita.

A regra da chave é a mesma para todas as suas contas. Leia capacidades.saqueQualquerChave em GET /v2/ex/config. Quando é true, a chave pode ser CPF, CNPJ, e-mail, telefone com +55 ou aleatória; a chave CPF tem de ser o favorecido.cpf e a chave CNPJ tem de ser o favorecido.cnpj. A chave de e-mail, telefone ou aleatória não é conferida com o documento informado: confira-a antes de enviar. A chave CNPJ com letra minúscula é lida em maiúscula. Quando é false, a chave tem de ser o próprio documento do favorecido, válido e sem pontuação, como no exemplo: o favorecido.cpf, com os 11 dígitos, ou o favorecido.cnpj, onde capacidades.favorecidoPJ é true. A chave CPF ou CNPJ de outro documento responde 400 chave_nao_pertence_ao_documento, a chave CNPJ onde capacidades.favorecidoPJ é false responde 400 favorecido_pj_nao_permitido, e e-mail, telefone, aleatória ou documento sem os dígitos verificadores 422 chave_exige_documento. Nos dois casos, a recusa não cria o saque.

Um saque acima do valor combinado, ou a partir do terceiro no dia ao mesmo favorecido (o número também pode ser combinado), ou que passe da soma do dia ao mesmo favorecido, nasce com status igual a AGUARDANDO_APROVACAO e o objeto aprovacao (as regras e o expiraEm). O valor fica reservado e o saque só sai quando um gestor da sua empresa o aprova no painel; sem decisão até aprovacao.expiraEm (24 horas, ou o enviarAte quando vem antes) ele termina NAO_REALIZADO e o valor volta. O evento é payout.aguardando_aprovacao, sem endToEndId: ele nasce de novo na aprovação, então use sempre o idEnvio. O mesmo acontece com o saque que você manda com exigirAprovacao igual a true, mesmo abaixo dessas regras: aprovacao.regras traz PEDIDA primeiro, junto das outras que o saque disparar. Um nome parecido e errado, como exigeAprovacao, responde 400 campo_desconhecido; confira no response o status e o eco exigirAprovacao, e prove o primeiro com R$ 1,00.

O gestor aprova ou recusa. aprovacao.desfecho é APROVADO, RECUSADO, EXPIRADO ou CANCELADO, e aprovacao.regras traz PEDIDA, VALOR, QUANTIDADE_DESTINO ou SOMA_DESTINO. Fora do aprovado, o saque termina NAO_REALIZADO com motivo.codigo MS02 (sua empresa recusou) ou MS03 (prazo vencido ou cancelado por nós), classe TERMINAL.

Com validadeSegundos, o envio não começa depois de enviarAte, e o saque que não saiu termina NAO_REALIZADO com o motivo MS03 e o valor volta. O envio que começou antes pode chegar à instituição depois, e o saque que ela aceitou segue até o desfecho dela. Se o envio ficou sem resposta, conferimos com a instituição antes de encerrar, alguns minutos depois de enviarAte. Espere o evento, e não o horário. Repetir o mesmo idEnvio devolve o enviarAte da primeira chamada, mas o mesmo idEnvio com e sem validadeSegundos responde 409 id_envio_duplicado. Um nome parecido e errado, como expiration, responde 400 campo_desconhecido.

Algumas contas não enviam Pix. Leia capacidades.saque em GET /v2/ex/config (com ?subconta= quando o saque sai de uma sub-conta): quando é false, o saque responde 503 capacidade_indisponivel e não é criado.

O saque reserva o valor mais a tarifa, que você vê no painel. Por isso um saque igual ao disponivel inteiro responde 422 saldo_insuficiente. Para sacar tudo, mande o saqueMaximo de Saldo: é o maior valor que cabe com a tarifa, até o centavo.

Algumas contas têm um valor máximo por Pix de saque. Acima dele o saque responde 422 valor_acima_do_maximo, com o máximo em detail, e não é criado. Nessas contas o saqueMaximo não passa desse máximo, e o resto sai em outro saque.

O desfecho chega pelo webhook payout.realizado ou payout.nao_realizado. Depois de um timeout ou 5xx, consulte GET /v2/ex/pix/{idEnvio} antes de repetir; se responder 404, repita o PUT com o mesmo idEnvio.

Erros #