Como solicitar saques e transferir valores para sua conta
Saques transferem valores da sua carteira disponível para uma conta bancária (TED) ou chave PIX.
Cada saque é feito na moeda da carteira debitada (currency). Se nenhuma conexão de liquidação puder pagar na moeda do saque, o saque inteiro falha (nunca parcialmente) e o valor debitado é devolvido à carteira.
Antes de solicitar um saque, consulte quais métodos estão habilitados:
curl -X GET https://api.worldfypayments.com/v1/withdrawals/methods \
-H "Authorization: Basic {credentials}"{
"data": {
"methods": ["pix", "ted"]
},
"message": "Métodos de saque habilitados"
}O array methods contém os métodos habilitados para o merchant (pix e/ou ted).
Consulte a taxa antes de solicitar:
curl -X GET "https://api.worldfypayments.com/v1/withdrawals/fee?amount=1000" \
-H "Authorization: Basic {credentials}"{
"data": {
"fee_fixed": 3.5,
"fee_rate": 0,
"calculated_fee": 3.5,
"amount": 1000
}
}| Campo | Descrição |
|---|---|
fee_fixed | Taxa fixa por saque (na unidade da moeda) |
fee_rate | Percentual variável aplicado (fração, ex: 0.01 = 1%) |
calculated_fee | Taxa total estimada (fee_fixed + parcela variável) |
amount | Valor informado na consulta (ou null) |
O parâmetro amount deste endpoint é opcional e informado na unidade da moeda (ex: reais). Ele é usado apenas para estimar a parcela variável da taxa. Observe que, na criação do saque, o campo amount é informado em centavos.
curl -X POST https://api.worldfypayments.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"
}'const response = await fetch('https://api.worldfypayments.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',
}),
});O campo amount é informado em centavos e representa o valor bruto que sai da carteira. A carteira debitada (wallet_id) deve pertencer ao merchant e ser do tipo available.
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.worldfypayments.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.worldfypayments.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"
}
}'| 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 conflito IDEMPOTENCY_CONFLICT sem criar um novo saque.
curl -X GET "https://api.worldfypayments.com/v1/withdrawals?status=completed¤cy=BRL&page=1&per_page=20" \
-H "Authorization: Basic {credentials}"| Parâmetro | Tipo | Descrição |
|---|---|---|
status | string | pending, processing, completed, failed ou canceled |
currency | string | Filtra por moeda (ex: BRL, USD, EUR) |
page | number | Página (padrão 1) |
per_page | number | Itens por página (padrão 20, máximo 100) |
curl -X GET https://api.worldfypayments.com/v1/withdrawals/{id} \
-H "Authorization: Basic {credentials}"Gera e retorna o comprovante da transferência em PNG (image/png) para download:
curl -X GET https://api.worldfypayments.com/v1/withdrawals/{id}/receipt \
-H "Authorization: Basic {credentials}" \
--output comprovante.png| 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.worldfypayments.com/v1/withdrawals/summary \
-H "Authorization: Basic {credentials}"Retorna saldo disponível, quantidade de saques pendentes, valor sacado hoje e totais acumulados.