Saques
Como solicitar saques e transferir valores para sua conta
O que são Saques?
Saques transferem valores da sua carteira disponível para uma conta bancária, chave PIX ou carteira de criptomoedas.
Métodos de Saque
Antes de solicitar um saque, consulte quais métodos estão habilitados:
curl -X GET https://api.payhubrasil.com.br/v1/withdrawals/methods \
-H "Authorization: Basic {credentials}"{
"data": [
{ "type": "pix", "enabled": true },
{ "type": "ted", "enabled": true },
{ "type": "crypto", "enabled": false }
]
}Taxa de Saque
Consulte a taxa antes de solicitar:
curl -X GET "https://api.payhubrasil.com.br/v1/withdrawals/fee?amount=100000" \
-H "Authorization: Basic {credentials}"{
"data": {
"fee": 350,
"fee_type": "fixed"
}
}Saques de Submerchants
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.payhubrasil.com.br/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.payhubrasil.com.br/v1/withdrawals?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"
curl -X GET "https://api.payhubrasil.com.br/v1/withdrawals/summary?submerchant_id={uuid}" \
-H "Authorization: Basic {credentials}"Solicitando um Saque
Via PIX
curl -X POST https://api.payhubrasil.com.br/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"
}'Documento do titular (chaves não-documento)
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.payhubrasil.com.br/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.
Via TED
curl -X POST https://api.payhubrasil.com.br/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"
}
Via Criptomoeda
curl -X POST https://api.payhubrasil.com.br/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"
}'Tipos de Chave PIX
| Tipo | Descrição |
|---|---|
cpf | CPF do titular |
cnpj | CNPJ do titular |
email | |
phone | Telefone |
random | Chave aleatória |
Chave de Idempotência
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 do Saque
| Status | Descrição |
|---|---|
pending | Solicitação criada, aguardando processamento |
processing | Em processamento |
completed | Concluído, valor transferido |
failed | Falha no processamento |
canceled | Cancelado |
Resumo de Saques
curl -X GET https://api.payhubrasil.com.br/v1/withdrawals/summary \
-H "Authorization: Basic {credentials}"Retorna saldo disponível, saques pendentes, valor sacado hoje e totais acumulados.