Criar Saque PIX

Criar um saque via 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"
}

POST

withdrawals

Criar um saque via 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"
}

Processamento assíncrono. A criação do saque retorna um status não-terminal (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.

Autorizações

Authorization

string

header

obrigatório

Access token obtido no POST /auth (client_id + client_secret). Válido por 300 segundos.

Cabeçalhos

Idempotency-Key

string

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.

Required string length: 8 - 255

X-Sub-Account

string

Reference 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.

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

Exemplo:

"loja-centro"

Corpo

application/json

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).

pixKey

string

obrigatório

Chave PIX do destinatário.

Exemplo:

"12345678901"

pixKeyType

enum<string>

obrigatório

Tipo da chave PIX.

Opções disponíveis:

cpf,

cnpj,

email,

phone,

random

Exemplo:

"cpf"

holderName

string

obrigatório

Nome do titular da conta PIX.

Exemplo:

"João da Silva"

holderDocument

string

obrigatório

CPF ou CNPJ do titular.

Exemplo:

"12345678901"

holderDocumentType

enum<string>

obrigatório

Tipo do documento do titular.

Opções disponíveis:

cpf,

cnpj

Exemplo:

"cpf"

projectId

string<uuid>

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.

Exemplo:

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

amount

number

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.

Intervalo obrigatório: x >= 1

Exemplo:

150.75

netAmount

number

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.

Intervalo obrigatório: x >= 1

Exemplo:

150

externalReference

string

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.

Maximum string length: 255

Exemplo:

"saque-empresa-001"

Resposta

Saque criado com sucesso

Dados do saque criado.

string<uuid>

obrigatório

ID do saque

Exemplo:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount

number

obrigatório

Valor do saque em BRL

Exemplo:

150.75

feeAmount

number

obrigatório

Valor da taxa em BRL

Exemplo:

2.5

netAmount

number

obrigatório

Valor líquido em BRL

Exemplo:

148.25

status

enum<string>

obrigatório

Status do saque

Opções disponíveis:

pending,

processing,

completed,

failed

Exemplo:

"completed"

snapshotHolderName

string

obrigatório

Nome do titular no momento do saque

Exemplo:

"João da Silva"

snapshotHolderDocument

string

obrigatório

Documento do titular no momento do saque

Exemplo:

"12345678901"

createdAt

string<date-time>

obrigatório

Data de criação

Exemplo:

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

projectId

string<uuid> | null

ID do projeto do saque (null quando não informado na criação e a conta tem 2+ projetos)

Exemplo:

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

snapshotPixKey

string | null

Chave PIX usada no momento do saque

Exemplo:

"12345678901"

snapshotPixKeyType

enum<string> | null

Tipo da chave PIX usada no momento do saque

Opções disponíveis:

cpf,

cnpj,

email,

phone,

random

Exemplo:

"cpf"

failureReason

string | null

Motivo da falha (quando status = failed)

Exemplo:

null

pspReference

string | null

Referência do PSP (provedor de pagamento)

Exemplo:

null

processedAt

string<date-time> | null

Data de processamento

Exemplo:

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

externalReference

string | null

Sua referência externa enviada na criação do saque (opcional)

Exemplo:

"saque-empresa-001"

Visão Geral

Autenticação

Conta

PIX

Saques

Transações

Bloqueios de Saldo

Projetos

Subcontas

Autorizações

Cabeçalhos

Corpo

Resposta