Create payout

Sends a Pix from your balance to the Pix key of the payee. The idEnvio is yours, and repeating the same idEnvio with the same body returns the same payout.

PUT /v2/ex/pix/{idEnvio}

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

Request fields #

Response fields #

Send a single document: favorecido.cpf or favorecido.cnpj. Both together respond 400 requisicao_invalida, and neither, or one with invalid check digits, 400 documento_invalido. The payee may be a legal entity when capacidades.favorecidoPJ is true in GET /v2/ex/config; when it is false, favorecido.cnpj responds 400 favorecido_pj_nao_permitido, and so does a CNPJ key with favorecido.cpf. When it is true, a CNPJ key with favorecido.cpf responds 400 chave_nao_pertence_ao_documento: declare the favorecido.cnpj of the owner of the key. In the response and in lookups, a payee that is a legal entity carries cnpj instead of cpf.

The document may be optional on your account: see documentoFavorecido.modo in GET /v2/ex/config. With OPCIONAL, the payout may come without favorecido.cpf and without favorecido.cnpj. With a CPF or CNPJ key, the document is the key itself. With an email, phone or random key, the payout goes out without a document, and the favorecido in the response has only the chave. A favorecido.cpf or favorecido.cnpj that is not a valid document is discarded, and the payout proceeds as if the field had not been sent; a document with punctuation that is valid without it is used, without the punctuation. When the account the payout goes out through requires the document, the response is 422 documento_exigido_pela_nominal: send the document and retry.

The key rule is the same for all your accounts. Read capacidades.saqueQualquerChave in GET /v2/ex/config. When it is true, the key may be a CPF, a CNPJ, an email, a phone number with +55 or a random key; a CPF key must be the favorecido.cpf and a CNPJ key must be the favorecido.cnpj. An email, phone or random key is not checked against the informed document: check it before sending. A CNPJ key with lowercase letters is read in uppercase. When it is false, the key must be the document of the payee, valid and without punctuation, as in the example: the favorecido.cpf, with all 11 digits, or the favorecido.cnpj, where capacidades.favorecidoPJ is true. A CPF or CNPJ key of another document responds 400 chave_nao_pertence_ao_documento, a CNPJ key where capacidades.favorecidoPJ is false responds 400 favorecido_pj_nao_permitido, and an email, phone, random key or document with invalid check digits 422 chave_exige_documento. In both cases, the rejection does not create the payout.

A payout above the agreed amount, or from the third one of the day to the same payee onward (the number can also be agreed), or that exceeds the daily total to the same payee, is created with status equal to AGUARDANDO_APROVACAO and the aprovacao object (the regras and the expiraEm). The amount stays reserved and the payout only goes out when a manager of your company approves it in the dashboard; with no decision by aprovacao.expiraEm (24 hours, or the enviarAte when that comes first) it ends NAO_REALIZADO and the amount returns. The event is payout.aguardando_aprovacao, without endToEndId: the identifier is generated again on approval, so always use the idEnvio. The same happens to a payout you send with exigirAprovacao equal to true, even below those rules: aprovacao.regras carries PEDIDA first, along with any others the payout triggers. A similar but wrong name, such as exigeAprovacao, responds 400 campo_desconhecido; check the status and the echoed exigirAprovacao in the response, and test the first one with R$ 1.00.

The manager approves or rejects. aprovacao.desfecho is APROVADO, RECUSADO, EXPIRADO or CANCELADO, and aprovacao.regras carries PEDIDA, VALOR, QUANTIDADE_DESTINO or SOMA_DESTINO. Unless approved, the payout ends NAO_REALIZADO with motivo.codigo MS02 (your company rejected it) or MS03 (deadline expired or cancelled by us), class TERMINAL.

With validadeSegundos, sending does not start after enviarAte, and a payout that did not go out ends NAO_REALIZADO with the reason MS03 and the amount returns. A sending that started earlier may reach the institution afterwards, and a payout the institution accepted proceeds to its outcome there. If the sending got no response, we check with the institution before closing it, a few minutes after enviarAte. Wait for the event, not for the clock. Repeating the same idEnvio returns the enviarAte of the first call, but the same idEnvio with and without validadeSegundos responds 409 id_envio_duplicado. A similar but wrong name, such as expiration, responds 400 campo_desconhecido.

Some accounts do not send Pix. Read capacidades.saque in GET /v2/ex/config (with ?subconta= when the payout comes from a sub-account): when it is false, the payout responds 503 capacidade_indisponivel and is not created.

The payout reserves the amount plus the fee, which you can see in the dashboard. That is why a payout equal to the whole disponivel responds 422 saldo_insuficiente. To withdraw everything, send the saqueMaximo from Balance: it is the largest amount that fits with the fee, down to the cent.

Some accounts have a maximum amount per payout Pix. Above it the payout responds 422 valor_acima_do_maximo, with the maximum in detail, and is not created. In those accounts the saqueMaximo does not go above that maximum, and the rest goes out in another payout.

The outcome arrives through the webhook payout.realizado or payout.nao_realizado. After a timeout or a 5xx, look up GET /v2/ex/pix/{idEnvio} before repeating; if it responds 404, repeat the PUT with the same idEnvio.

Errors #