Solicitar saque da subconta
POST
/api/subaccounts/{{subaccount_id}}/withdrawals
Operação delegada (white-label)
{{subaccount_id}}. Autenticada pela API Key do master — por isso não exige TOTP (a credencial é a do master).subaccounts:writeBody
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | sim | Valor bruto em REAIS (ex: 95.00). Mínimo R$ 1,00. A taxa de saque da subconta é descontada → netAmount. |
pixKeyId | string | sim | ID de uma chave PIX da própria subconta com status APPROVED. |
Regras de negócio
pixKeyId precisa pertencer à subconta e estar APPROVED. Chave de outro usuário → 404 (não encontrada). Chave não aprovada → 400.PENDING/PROCESSING por vez → 400 ("Você já tem um saque pendente").amount; saldo mínimo de R$ 4,00.status: PROCESSING (transparente para o integrador).Resposta 200 OK
{ withdrawal: { id, amount, fee, netAmount, status, pixKey: { type, key }, createdAt } }.amount, fee, netAmount em CENTAVOS.pixKey.key vem mascarada (ex: 123.***.***-89).status tipicamente PROCESSING (ou NEEDS_REVIEW em casos de verificação Treeal).Sigilo (crítico): a feeretornada é a taxa de saque cheia da subconta. Nenhuma comissão/base do master é exposta.
Códigos de erro
| HTTP | Quando |
|---|---|
400 | Saldo insuficiente, valor abaixo do mínimo, chave não aprovada, já há saque pendente, ou payout falhou (estornado). |
401 | API Key ausente/inválida. |
404 | Master sem white-label, subconta não-sua, chave PIX inexistente ou de outro usuário. |
503 | Sem liquidez Treeal no momento ("Saque temporariamente indisponível"). |
Exemplo cURL
429 ao exceder).Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff '/api/subaccounts/{{subaccount_id}}/withdrawals' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 95.00,
"pixKeyId": "{{pix_key_id}}"
}'Response Response Example
200 - Sucesso (200) — saque em processamento
{
"withdrawal": {
"id": "clwd0001",
"amount": 9500,
"fee": 500,
"netAmount": 9000,
"status": "PROCESSING",
"pixKey": {
"type": "CPF",
"key": "123.***.***-89"
},
"createdAt": "2026-05-07T14:40:00.000Z"
}
}Modificado em 2026-07-02 06:57:27