Create PIX Withdrawal

Create a PIX withdrawal

curl --request POST \
  --url https://api-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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-gateway.pague.dev/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.

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

Authorizations

Headers

Body

Response