curl --request POST \
--url https://api.brazilpix.com/v2/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"pixKey": "12345678901",
"pixKeyType": "cpf",
"holderName": "João da Silva",
"holderDocument": "12345678901",
"holderDocumentType": "cpf",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 150.75,
"netAmount": 150,
"externalReference": "saque-empresa-001"
}
'import requests
url = "https://api.brazilpix.com/v2/withdrawals"
payload = {
"pixKey": "12345678901",
"pixKeyType": "cpf",
"holderName": "João da Silva",
"holderDocument": "12345678901",
"holderDocumentType": "cpf",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 150.75,
"netAmount": 150,
"externalReference": "saque-empresa-001"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
pixKey: '12345678901',
pixKeyType: 'cpf',
holderName: 'João da Silva',
holderDocument: '12345678901',
holderDocumentType: 'cpf',
projectId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 150.75,
netAmount: 150,
externalReference: 'saque-empresa-001'
})
};
fetch('https://api.brazilpix.com/v2/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brazilpix.com/v2/withdrawals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'pixKey' => '12345678901',
'pixKeyType' => 'cpf',
'holderName' => 'João da Silva',
'holderDocument' => '12345678901',
'holderDocumentType' => 'cpf',
'projectId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 150.75,
'netAmount' => 150,
'externalReference' => 'saque-empresa-001'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brazilpix.com/v2/withdrawals"
payload := strings.NewReader("{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brazilpix.com/v2/withdrawals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brazilpix.com/v2/withdrawals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": 150.75,
"feeAmount": 2.5,
"netAmount": 148.25,
"status": "completed",
"snapshotHolderName": "João da Silva",
"snapshotHolderDocument": "12345678901",
"createdAt": "2026-02-10T14:30:00.000Z",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"snapshotPixKey": "12345678901",
"snapshotPixKeyType": "cpf",
"failureReason": null,
"pspReference": null,
"processedAt": "2026-02-10T14:30:01.000Z",
"externalReference": "saque-empresa-001"
}{
"statusCode": 400,
"error": "BadRequest",
"message": "name must be longer than or equal to 2 characters",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication token is required",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "You do not have permission to access this resource",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 404,
"error": "NotFound",
"message": "Resource with id 550e8400-e29b-41d4-a716-446655440000 not found",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {
"resource": "Example",
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"traceId": "<string>"
}{
"statusCode": 500,
"error": "InternalError",
"message": "An unexpected error occurred",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "2771463d58840c8e116dc6dda1e1e5d0"
}Criar Saque PIX
Cria um novo saque via PIX informando os dados da chave PIX e do titular da conta destino.
Permissão requerida: WITHDRAWAL:WRITE ou FULL_ACCESS
Restrição de IP: Se a credencial tiver uma lista de IPs permitidos configurada, requisições fora dela são rejeitadas com 403. Recomendado para credenciais com esta permissão.
curl --request POST \
--url https://api.brazilpix.com/v2/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"pixKey": "12345678901",
"pixKeyType": "cpf",
"holderName": "João da Silva",
"holderDocument": "12345678901",
"holderDocumentType": "cpf",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 150.75,
"netAmount": 150,
"externalReference": "saque-empresa-001"
}
'import requests
url = "https://api.brazilpix.com/v2/withdrawals"
payload = {
"pixKey": "12345678901",
"pixKeyType": "cpf",
"holderName": "João da Silva",
"holderDocument": "12345678901",
"holderDocumentType": "cpf",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 150.75,
"netAmount": 150,
"externalReference": "saque-empresa-001"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
pixKey: '12345678901',
pixKeyType: 'cpf',
holderName: 'João da Silva',
holderDocument: '12345678901',
holderDocumentType: 'cpf',
projectId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 150.75,
netAmount: 150,
externalReference: 'saque-empresa-001'
})
};
fetch('https://api.brazilpix.com/v2/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brazilpix.com/v2/withdrawals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'pixKey' => '12345678901',
'pixKeyType' => 'cpf',
'holderName' => 'João da Silva',
'holderDocument' => '12345678901',
'holderDocumentType' => 'cpf',
'projectId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 150.75,
'netAmount' => 150,
'externalReference' => 'saque-empresa-001'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brazilpix.com/v2/withdrawals"
payload := strings.NewReader("{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brazilpix.com/v2/withdrawals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brazilpix.com/v2/withdrawals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pixKey\": \"12345678901\",\n \"pixKeyType\": \"cpf\",\n \"holderName\": \"João da Silva\",\n \"holderDocument\": \"12345678901\",\n \"holderDocumentType\": \"cpf\",\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 150.75,\n \"netAmount\": 150,\n \"externalReference\": \"saque-empresa-001\"\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": 150.75,
"feeAmount": 2.5,
"netAmount": 148.25,
"status": "completed",
"snapshotHolderName": "João da Silva",
"snapshotHolderDocument": "12345678901",
"createdAt": "2026-02-10T14:30:00.000Z",
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"snapshotPixKey": "12345678901",
"snapshotPixKeyType": "cpf",
"failureReason": null,
"pspReference": null,
"processedAt": "2026-02-10T14:30:01.000Z",
"externalReference": "saque-empresa-001"
}{
"statusCode": 400,
"error": "BadRequest",
"message": "name must be longer than or equal to 2 characters",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication token is required",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "You do not have permission to access this resource",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 404,
"error": "NotFound",
"message": "Resource with id 550e8400-e29b-41d4-a716-446655440000 not found",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {
"resource": "Example",
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"traceId": "<string>"
}{
"statusCode": 500,
"error": "InternalError",
"message": "An unexpected error occurred",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "2771463d58840c8e116dc6dda1e1e5d0"
}pending ou processing) — o desfecho definitivo é sempre entregue via webhook (withdrawal.completed ou withdrawal.failed). Trate o webhook como a fonte da verdade; não trate a resposta da criação como resultado final.Erros de validação (saldo insuficiente, limite excedido, dados inválidos) retornam erro na própria chamada.Fila de envio
Depois de aceito, o saque entra numa fila de envio à instituição de pagamento. Na maior parte do tempo o envio é imediato; em picos de volume pode levar de segundos a minutos, e o saque permanece emprocessing enquanto espera.
- Ordem de chegada. Os saques são enviados na ordem em que foram criados.
- Chave inexistente custa caro. Cada saque consulta a chave PIX de destino no DICT, e o Banco Central limita essas consultas — uma consulta a chave que não existe consome muito mais do limite do que uma bem-sucedida. Quando uma conta acumula recusas por chave inexistente ou inválida, os próximos saques dela perdem prioridade na fila e esperam mais. Valide as chaves antes de enviar e não use o saque para testar se uma chave existe.
- Bloqueio de consulta de chaves. Se a instituição sinalizar que o limite de consultas foi atingido, os saques ainda não enviados aguardam na fila até a liberação. Os que já tinham sido enviados podem voltar como
withdrawal_failed, com o valor devolvido ao saldo. - Prazo máximo. Um saque que não consiga ser enviado em até 6 horas falha (
withdrawal_failed) e o valor reservado volta para o saldo.
Autorizações
Access token obtido no POST /auth (client_id + client_secret). Válido por 300 segundos.
Cabeçalhos
Chave única do cliente (8-255 chars) que torna a requisição idempotente. Retentativas com a mesma chave retornam a resposta cacheada (TTL 24h). Mesma chave com body diferente retorna 422.
8 - 255Reference da subconta em que a operação deve ser executada. Quando omitido, a operação acontece na conta principal; o valor reservado principal também resolve para a conta principal e é equivalente a omitir o header. Aceito em todos os endpoints, exceto POST /auth e os próprios endpoints de /sub-accounts, que sempre operam na conta principal.
Erros possíveis: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.
Exige que a credencial tenha o acesso a subcontas habilitado (Configurações → Integração → Credenciais de API). Ele nasce desligado e não é substituído por nenhuma permissão, nem por FULL_ACCESS: sem ele a resposta é 403 SUB_ACCOUNT_FORBIDDEN.
^[a-z0-9][a-z0-9_-]{1,31}$"loja-centro"
Corpo
Dados para criar um saque via PIX. Informe exatamente um entre amount (valor bruto debitado do saldo) ou netAmount (valor líquido que o destinatário deve receber).
Chave PIX do destinatário.
"12345678901"
Tipo da chave PIX.
cpf, cnpj, email, phone, random "cpf"
Nome do titular da conta PIX.
"João da Silva"
CPF ou CNPJ do titular.
"12345678901"
Tipo do documento do titular.
cpf, cnpj "cpf"
ID do projeto ao qual o saque pertence. Se não informado e a conta tiver um único projeto, o saque herda esse projeto; com mais de um projeto, o saque fica sem projeto — mesmo comportamento da criação de cobrança PIX.
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
Valor bruto em BRL debitado do saldo. O destinatário recebe amount - feeAmount. Mínimo R$ 1,00. Informe amount OU netAmount — nunca os dois.
x >= 1150.75
Valor líquido em BRL que o destinatário deve receber. A API calcula o gross necessário (gross = netAmount + feeAmount) e debita esse total do saldo. Mínimo R$ 1,00. Informe amount OU netAmount — nunca os dois.
x >= 1150
Seu ID de referência externa (opcional). É devolvido no response e nos webhooks withdrawal_completed e withdrawal_failed para facilitar a reconciliação com seus sistemas internos.
255"saque-empresa-001"
Resposta
Saque criado com sucesso
Dados do saque criado.
ID do saque
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Valor do saque em BRL
150.75
Valor da taxa em BRL
2.5
Valor líquido em BRL
148.25
Status do saque
pending, processing, completed, failed "completed"
Nome do titular no momento do saque
"João da Silva"
Documento do titular no momento do saque
"12345678901"
Data de criação
"2026-02-10T14:30:00.000Z"
ID do projeto do saque (null quando não informado na criação e a conta tem 2+ projetos)
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
Chave PIX usada no momento do saque
"12345678901"
Tipo da chave PIX usada no momento do saque
cpf, cnpj, email, phone, random "cpf"
Motivo da falha (quando status = failed)
null
Referência do PSP (provedor de pagamento)
null
Data de processamento
"2026-02-10T14:30:01.000Z"
Sua referência externa enviada na criação do saque (opcional)
"saque-empresa-001"