Como fazer um saque

Este guia mostra como realizar saques para chaves PIX e consultar o saldo disponível em sua conta. Todas as operações de saque devem ser realizadas exclusivamente no backend por questões de segurança.

IMPORTANTE: A Chave de Cash-Out nunca deve ser exposta no client-side. Sempre use-a apenas em seu backend para garantir a segurança das operações financeiras.

Pré-requisitos

Antes de realizar um saque, certifique-se de ter:

✅ Chave de Cash-Out configurada (obtida na plataforma)
✅ Saldo disponível na conta
✅ Chave PIX válida para receber o saque
✅ Ambiente backend seguro para processar a requisição

Consultar Saldo

Antes de realizar um saque, é recomendado consultar o saldo disponível:

Endpoint de Consulta de Saldo

curl -X GET https://api.exemplo.com/v1/balance \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT"

Resposta

A resposta conterá o saldo disponível e o saldo pendente:

{
  "available_amount": 10500,
  "pending_amount": 2500,
  "currency": "BRL",
  "updated_at": "2024-01-15T10:00:00Z"
}

Campos da resposta:

available_amount: Saldo disponível para saque (em centavos)
pending_amount: Saldo pendente de confirmação (em centavos)
currency: Moeda (sempre "BRL")
updated_at: Data e hora da última atualização

O saldo é atualizado em tempo real. Sempre consulte antes de realizar saques para garantir que há saldo suficiente.

Realizar um Saque

Preparar a Requisição

Use o endpoint POST /withdrawals com a Chave de Cash-Out:

curl -X POST https://api.exemplo.com/v1/withdrawals \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "pix_key": "usuario@exemplo.com"
  }'

Processar a Resposta

A resposta conterá as informações do saque criado:

{
  "id": "wth_123456789",
  "status": "pending",
  "amount": 5000,
  "currency": "BRL",
  "pix_key": "usuario@exemplo.com",
  "created_at": "2024-01-15T10:00:00Z",
  "processed_at": null,
  "estimated_completion": "2024-01-15T14:00:00Z"
}

Status possíveis:

pending: Saque aguardando processamento
processing: Saque sendo processado
completed: Saque concluído com sucesso
failed: Saque falhou (verificar motivo)

Monitorar o Status

Você pode consultar o status do saque usando o ID retornado:

curl -X GET https://api.exemplo.com/v1/withdrawals/wth_123456789 \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT"

Segurança

Boas Práticas

Nunca exponha a Chave de Cash-Out
- Não use em código JavaScript
- Não inclua em aplicações mobile
- Não compartilhe em repositórios públicos
Use variáveis de ambiente
```
# .env
CASH_OUT_KEY=sua_chave_aqui
```

Valide sempre o saldo antes de sacar

const balance = await getBalance();
if (balance.available_amount < requestedAmount) {
  throw new Error('Saldo insuficiente');
}

Implemente rate limiting
- Limite o número de saques por período
- Adicione validações adicionais para valores altos
Registre todas as operações
- Mantenha logs de todas as requisições de saque
- Monitore tentativas de saque falhadas

Se você suspeitar que sua Chave de Cash-Out foi comprometida, revogue-a imediatamente na plataforma e gere uma nova.

Exemplos Completos

Node.js/TypeScript

async function checkBalanceAndWithdraw(amount: number, pixKey: string) {
  // 1. Consultar saldo
  const balanceResponse = await fetch('https://api.exemplo.com/v1/balance', {
    headers: {
      Authorization: `Bearer ${process.env.CASH_OUT_KEY}`,
    },
  });

  const balance = await balanceResponse.json();

  // 2. Validar saldo
  if (balance.available_amount < amount) {
    throw new Error('Saldo insuficiente');
  }

  // 3. Realizar saque
  const withdrawalResponse = await fetch(
    'https://api.exemplo.com/v1/withdrawals',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.CASH_OUT_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount,
        pix_key: pixKey,
      }),
    }
  );

  const withdrawal = await withdrawalResponse.json();
  return withdrawal;
}

Python

import os
import requests

def check_balance_and_withdraw(amount, pix_key):
    token = os.getenv('CASH_OUT_KEY')
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    # 1. Consultar saldo
    balance_response = requests.get(
        'https://api.exemplo.com/v1/balance',
        headers=headers
    )
    balance = balance_response.json()

    # 2. Validar saldo
    if balance['available_amount'] < amount:
        raise ValueError('Saldo insuficiente')

    # 3. Realizar saque
    withdrawal_data = {
        'amount': amount,
        'pix_key': pix_key
    }

    withdrawal_response = requests.post(
        'https://api.exemplo.com/v1/withdrawals',
        headers=headers,
        json=withdrawal_data
    )

    withdrawal = withdrawal_response.json()
    return withdrawal

Listar Saques

Você também pode listar todos os saques realizados:

curl -X GET https://api.exemplo.com/v1/withdrawals \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT"

Com filtros opcionais:

curl -X GET "https://api.exemplo.com/v1/withdrawals?status=completed&limit=10" \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT"

Próximos Passos

Veja a Referência Completa de API de Saques
Configure webhooks para receber notificações de conclusão de saques
Aprenda sobre autenticação e segurança

Como fazer um saque

On this page