Создать вывод средств через PIX

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

Вывод средств

Создать вывод средств PIX

Создаёт новый вывод средств через PIX с указанием данных ключа PIX и владельца счёта назначения.

Требуемое разрешение: WITHDRAWAL:WRITE или FULL_ACCESS

Ограничение по IP: если для учётных данных настроен список разрешённых IP-адресов, запросы вне этого списка отклоняются с кодом 403. Рекомендуется для учётных данных с этим разрешением.

POST

withdrawals

Создать вывод средств через PIX

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

Асинхронная обработка. Создание вывода возвращает нетерминальный статус (pending или processing) — окончательный результат всегда доставляется через вебхук (withdrawal.completed или withdrawal.failed). Считайте вебхук источником истины; не считайте ответ на создание окончательным результатом.Ошибки валидации (недостаточный баланс, превышение лимита, неверные данные) возвращают ошибку в самом вызове.

Авторизации

Authorization

string

header

обязательно

Токен доступа, полученный через POST /auth (client_id + client_secret). Действителен в течение 300 секунд.

Заголовки

Idempotency-Key

string

Уникальный клиентский ключ (8–255 символов), делающий запрос идемпотентным. Повторные запросы с тем же ключом возвращают закешированный ответ (TTL 24 ч). Тот же ключ с другим телом запроса возвращает 422.

Required string length: 8 - 255

X-Sub-Account

string

Reference субсчёта, в котором должна выполняться операция. Если заголовок не передан, операция выполняется в основном аккаунте; зарезервированное значение principal также указывает на основной аккаунт и равнозначно отсутствию заголовка. Принимается всеми эндпоинтами, кроме POST /auth и самих эндпоинтов /sub-accounts, которые всегда работают с основным аккаунтом.

Возможные ошибки: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.

Требует, чтобы у учётных данных был включён доступ к субсчетам (Настройки → Интеграция → Учётные данные API). По умолчанию он выключен и не заменяется никаким разрешением, даже FULL_ACCESS: без него ответ — 403 SUB_ACCOUNT_FORBIDDEN.

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

Пример:

"loja-centro"

Тело

application/json

Данные для создания вывода средств через PIX. Укажите ровно одно из полей: amount (валовая сумма, списываемая с баланса) или netAmount (чистая сумма, которую должен получить получатель).

pixKey

string

обязательно

Ключ PIX получателя.

Пример:

"12345678901"

pixKeyType

enum<string>

обязательно

Тип ключа PIX.

Доступные опции:

cpf,

cnpj,

email,

phone,

random

Пример:

"cpf"

holderName

string

обязательно

Имя владельца счёта PIX.

Пример:

"João da Silva"

holderDocument

string

обязательно

CPF или CNPJ владельца.

Пример:

"12345678901"

holderDocumentType

enum<string>

обязательно

Тип документа владельца.

Доступные опции:

cpf,

cnpj

Пример:

"cpf"

projectId

string<uuid>

ID проекта, к которому относится вывод. Если не указан и у аккаунта один проект, вывод наследует этот проект; если проектов несколько — вывод создаётся без проекта (так же, как при создании PIX-платежа).

Пример:

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

amount

number

Валовая сумма в BRL, списываемая с баланса. Получатель получает amount - feeAmount. Минимум R$ 1,00. Укажите amount ИЛИ netAmount — никогда оба одновременно.

Требуемый диапазон: x >= 1

Пример:

150.75

netAmount

number

Чистая сумма в BRL, которую должен получить получатель. API вычисляет необходимую валовую сумму (gross = netAmount + feeAmount) и списывает её с баланса. Минимум R$ 1,00. Укажите amount ИЛИ netAmount — никогда оба одновременно.

Требуемый диапазон: x >= 1

Пример:

150

externalReference

string

Ваш внешний референс-ID (необязательно). Возвращается в ответе и в вебхуках withdrawal_completed и withdrawal_failed для упрощения сверки с вашими внутренними системами.

Maximum string length: 255

Пример:

"saque-empresa-001"

Ответ

Вывод средств успешно создан

Данные созданного вывода средств.

string<uuid>

обязательно

ID вывода средств

Пример:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount

number

обязательно

Сумма вывода средств в BRL

Пример:

150.75

feeAmount

number

обязательно

Сумма комиссии в BRL

Пример:

2.5

netAmount

number

обязательно

Чистая сумма в BRL

Пример:

148.25

status

enum<string>

обязательно

Статус вывода средств

Доступные опции:

pending,

processing,

completed,

failed

Пример:

"completed"

snapshotHolderName

string

обязательно

Имя владельца в момент вывода средств

Пример:

"João da Silva"

snapshotHolderDocument

string

обязательно

Документ владельца в момент вывода средств

Пример:

"12345678901"

createdAt

string<date-time>

обязательно

Дата создания

Пример:

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

projectId

string<uuid> | null

ID проекта вывода (null, если не указан при создании и у аккаунта 2+ проекта)

snapshotPixKey

string | null

Ключ PIX, использованный в момент вывода средств

Пример:

"12345678901"

snapshotPixKeyType

enum<string> | null

Тип ключа PIX, использованного в момент вывода средств

Доступные опции:

cpf,

cnpj,

email,

phone,

random

Пример:

"cpf"

failureReason

string | null

Причина сбоя (когда status = failed)

Пример:

null

pspReference

string | null

Референс PSP (платёжного провайдера)

Пример:

null

processedAt

string<date-time> | null

Дата обработки

Пример:

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

externalReference

string | null

Ваш внешний референс, отправленный при создании вывода средств (необязательно)

Пример:

"saque-empresa-001"

Обзор

Аутентификация

Аккаунт

PIX

Вывод средств

Транзакции

Блокировки баланса

Проекты

Субсчета

Создать вывод средств PIX

Авторизации

Заголовки

Тело

Ответ