Create PIX Withdrawal

Create a PIX withdrawal

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"
}

POST

withdrawals

Create a PIX withdrawal

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"
}

Asynchronous processing. Withdrawal creation returns a non-terminal status (pending or processing) — the definitive outcome is always delivered via webhook (withdrawal.completed or withdrawal.failed). Treat the webhook as the source of truth; do not treat the creation response as the final result.Validation errors (insufficient balance, limit exceeded, invalid data) return an error in the call itself.

Dispatch queue

Once accepted, the withdrawal enters a queue to be sent to the payment institution. Most of the time it is sent immediately; during volume peaks it can take from seconds to minutes, and the withdrawal stays in processing while it waits.

First come, first served. Withdrawals are sent in the order they were created.
Nonexistent keys are expensive. Every withdrawal looks up the destination PIX key in DICT, and the Central Bank limits those lookups — a lookup for a key that does not exist consumes far more of the limit than a successful one. When an account accumulates refusals for nonexistent or invalid keys, its next withdrawals lose priority in the queue and wait longer. Validate keys before sending and do not use withdrawals to test whether a key exists.
Key lookup block. If the institution signals that the lookup limit has been reached, withdrawals not yet sent wait in the queue until it is lifted. Those already sent may come back as withdrawal_failed, with the amount returned to your balance.
Maximum wait. A withdrawal that cannot be sent within 6 hours fails (withdrawal_failed) and the reserved amount returns to your balance.

In every case the outcome arrives by webhook.

Authorizations

Authorization

string

header

required

Access token obtained from POST /auth (client_id + client_secret). Valid for 300 seconds.

Headers

Idempotency-Key

string

Unique client-provided key (8-255 chars) that makes the request idempotent. Retries with the same key return the cached response (24h TTL). The same key with a different body returns 422.

Required string length: 8 - 255

X-Sub-Account

string

Reference of the sub-account the operation runs against. When omitted, the operation happens on the main account; the reserved value principal also resolves to the main account and is equivalent to omitting the header. Accepted on every endpoint except POST /auth and the /sub-accounts endpoints themselves, which always operate on the main account.

Possible errors: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.

Requires the credential to have sub-account access enabled (Settings → Integration → API Credentials). It starts turned off and is not replaced by any permission, not even FULL_ACCESS: without it the response is 403 SUB_ACCOUNT_FORBIDDEN.

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$

Example:

"loja-centro"

Body

application/json

Data to create a PIX withdrawal. Provide exactly one of amount (gross amount debited from the balance) or netAmount (net amount the recipient should receive).

pixKey

string

required

Recipient's PIX key.

Example:

"12345678901"

pixKeyType

enum<string>

required

PIX key type.

Available options:

cpf,

cnpj,

email,

phone,

random

Example:

"cpf"

holderName

string

required

PIX account holder's name.

Example:

"João da Silva"

holderDocument

string

required

Account holder's CPF or CNPJ.

Example:

"12345678901"

holderDocumentType

enum<string>

required

Holder's document type.

Available options:

cpf,

cnpj

Example:

"cpf"

projectId

string<uuid>

ID of the project the withdrawal belongs to. If omitted, the withdrawal inherits the account's project when there is a single one; with multiple projects the withdrawal is created without a project — same behavior as PIX charge creation.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

amount

number

Gross amount in BRL debited from the balance. The recipient receives amount - feeAmount. Minimum R$ 1.00. Provide amount OR netAmount — never both.

Required range: x >= 1

Example:

150.75

netAmount

number

Net amount in BRL the recipient should receive. The API computes the required gross (gross = netAmount + feeAmount) and debits that total from the balance. Minimum R$ 1.00. Provide amount OR netAmount — never both.

Required range: x >= 1

Example:

150

externalReference

string

Your external reference ID (optional). It is returned in the response and in the withdrawal_completed and withdrawal_failed webhooks to make reconciliation with your internal systems easier.

Maximum string length: 255

Example:

"saque-empresa-001"

Response

Withdrawal created successfully

Details of the created withdrawal.

string<uuid>

required

Withdrawal ID

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount

number

required

Withdrawal amount in BRL

Example:

150.75

feeAmount

number

required

Fee amount in BRL

Example:

2.5

netAmount

number

required

Net amount in BRL

Example:

148.25

status

enum<string>

required

Withdrawal status

Available options:

pending,

processing,

completed,

failed

Example:

"completed"

snapshotHolderName

string

required

Holder's name at the time of the withdrawal

Example:

"João da Silva"

snapshotHolderDocument

string

required

Holder's document at the time of the withdrawal

Example:

"12345678901"

createdAt

string<date-time>

required

Creation date

Example:

"2026-02-10T14:30:00.000Z"

projectId

string<uuid> | null

Project ID of the withdrawal (null when not provided at creation and the account has 2+ projects)

snapshotPixKey

string | null

PIX key used at the time of the withdrawal

Example:

"12345678901"

snapshotPixKeyType

enum<string> | null

Type of the PIX key used at the time of the withdrawal

Available options:

cpf,

cnpj,

email,

phone,

random

Example:

"cpf"

failureReason

string | null

Failure reason (when status = failed)

Example:

null

pspReference

string | null

PSP (payment service provider) reference

Example:

null

processedAt

string<date-time> | null

Processing date

Example:

"2026-02-10T14:30:01.000Z"

externalReference

string | null

Your external reference sent when the withdrawal was created (optional)

Example:

"saque-empresa-001"

Overview

Authentication

Account

PIX

Withdrawals

Transactions

Balance Blocks

Projects

Sub-accounts

Create PIX Withdrawal

Dispatch queue

Authorizations

Headers

Body

Response

​Dispatch queue

Authorizations

Headers

Body

Response

Dispatch queue