Como solicitar saques e transferir valores para sua conta
Saques transferem valores da sua carteira disponível para uma conta bancária, chave PIX ou carteira de criptomoedas.
Antes de solicitar um saque, consulte quais métodos estão habilitados:
curl -X GET https://api.payhubr.com/v1/withdrawals/methods \
-H "Authorization: Basic {credentials}"{
"data": [
{ "type": "pix", "enabled": true },
{ "type": "ted", "enabled": true },
{ "type": "crypto", "enabled": false }
]
}Consulte a taxa antes de solicitar:
curl -X GET "https://api.payhubr.com/v1/withdrawals/fee?amount=100000" \
-H "Authorization: Basic {credentials}"{
"data": {
"fee": 350,
"fee_type": "fixed"
}
}Merchants podem solicitar saques em nome de seus submerchants passando o campo opcional submerchant_id. A carteira (wallet_id) deve pertencer ao submerchant informado.
curl -X POST https://api.payhubr.com/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "pix",
"wallet_id": "carteira-do-submerchant-uuid",
"submerchant_id": "submerchant-uuid",
"amount": 50000,
"idempotency_key": "saque-sub-001",
"pix_key": "12345678901",
"pix_key_type": "cpf"
}'Para filtrar saques e resumo por submerchant, passe submerchant_id como query param:
curl -X GET "https://api.payhubr.com/v1/withdrawals?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"
curl -X GET "https://api.payhubr.com/v1/withdrawals/summary?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"curl -X POST https://api.payhubr.com/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "pix",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 100000,
"idempotency_key": "saque-2026-02-11-001",
"pix_key": "12345678901",
"pix_key_type": "cpf"
}'Quando a chave PIX não é do tipo cpf ou cnpj (ou seja, email, phone ou random), é obrigatório enviar o documento do titular nos campos holder_document_type e holder_document_number. A API retornará erro HOLDER_DOCUMENT_REQUIRED caso esses campos não sejam enviados.
curl -X POST https://api.payhubr.com/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "pix",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 100000,
"idempotency_key": "saque-2026-02-11-004",
"pix_key": "usuario@email.com",
"pix_key_type": "email",
"holder_document_type": "cpf",
"holder_document_number": "12345678901"
}'| Campo | Tipo | Descrição |
|---|---|---|
holder_document_type | cpf | cnpj | Tipo do documento do titular da chave PIX |
holder_document_number | string (11-14 dígitos) | Número do documento (apenas dígitos) |
Saques via API para chaves do tipo email, phone e random serão rejeitados com erro HOLDER_DOCUMENT_REQUIRED se esses campos não forem enviados.
curl -X POST https://api.payhubr.com/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "ted",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 500000,
"idempotency_key": "saque-2026-02-11-002",
"bank_account": {
"bank_code": "001",
"branch_number": "1234",
"account_number": "567890",
"account_check_digit": "1",
"account_type": "checking",
"holder_name": "João Silva",
"holder_tax_id": "12345678901"
}
curl -X POST https://api.payhubr.com/v1/withdrawals \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "crypto",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 200000,
"idempotency_key": "saque-2026-02-11-003",
"crypto_currency": "USDT",
"crypto_network": "tron",
"crypto_wallet": "TXyz1234567890abcdef"
}'| Tipo | Descrição |
|---|---|
cpf | CPF do titular |
cnpj | CNPJ do titular |
email | |
phone | Telefone |
random | Chave aleatória |
O campo idempotency_key garante que uma mesma solicitação de saque não seja processada mais de uma vez. Use um identificador único por saque.
Sempre envie uma idempotency_key única. Se uma requisição for repetida com a mesma chave, a API retornará o resultado da solicitação original sem criar um novo saque.
| Status | Descrição |
|---|---|
pending | Solicitação criada, aguardando processamento |
processing | Em processamento |
completed | Concluído, valor transferido |
failed | Falha no processamento |
canceled | Cancelado |
curl -X GET https://api.payhubr.com/v1/withdrawals/summary \
-H "Authorization: Basic {credentials}"Retorna saldo disponível, saques pendentes, valor sacado hoje e totais acumulados.
const response = await fetch('https://api.payhubr.com/v1/withdrawals', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'pix',
wallet_id: '550e8400-e29b-41d4-a716-446655440000',
amount: 100000,
idempotency_key: 'saque-2026-02-11-001',
pix_key: '12345678901',
pix_key_type: 'cpf',
}),
});