Solicitar Saque PIX

Parâmetros do Request

Autorização do saque: IP autorizado ou Secret de saque

Cada POST /v1/withdrawals passa pela API Key e por um destes dois fatores:

• Com o Saque via Secret habilitado, uma requisição sem o header ainda é aceita se sair de um IP autorizado.
• Integrando por uma plataforma de pagamentos que pede o "Secret de Saque" da ActivePayments? É este mesmo valor: copie na tela de Regras de Segurança e cole lá.
• O secret autoriza saques: guarde só no servidor, nunca em front-end ou app. Se vazar, use Resetar. O anterior para de valer na hora, e o reset pede o código da verificação em duas etapas.
• A mesma regra vale para o saque de subconta e para a conversão USDT.

Tipos de Chave PIX

Exemplos de Código

curl -X POST "https://api.activepayments.com.br/api/v1/withdrawals" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "x-withdrawal-secret: SEU_SECRET_DE_SAQUE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "pixKeyType": "email",
    "pixKey": "destinatario@email.com",
    "externalReference": "SAQUE-12345"
  }'

Resposta

A API retorna os dados do saque criado, incluindo o ID para consulta posterior:

{
  "success": true,
  "data": {
    "withdrawalId": "34af7934-9991-41ea-aabc-e8601e98c8fb",
    "amount": "10",
    "fee": "1",
    "netAmount": "10",
    "totalDebited": "11",
    "status": "PENDING",
    "pixKey": "yur***com",
    "pixKeyType": "EMAIL",
    "createdAt": "2026-01-08T04:58:06.974Z",
    "message": "Saque solicitado com sucesso. Aguardando processamento."
  }
}

Campos da Resposta

• withdrawalId: ID único do saque (use para consultar o status)
• amount: Valor solicitado, que é o que chega ao destinatário (string com decimal — ex: "10.00")
• fee: Taxa cobrada pela transferência (string)
• netAmount: Valor transferido ao destinatário — igual a amount (string)
• totalDebited: amount + fee, o que efetivamente sai do seu saldo (string)
• status: Status atual do saque em uppercase (PENDING, APPROVED, PROCESSING, COMPLETED, REJECTED, FAILED)
• pixKey: Chave PIX (parcialmente mascarada)
• pixKeyType: Tipo da chave em uppercase (CPF, CNPJ, EMAIL, PHONE, EVP)
• createdAt: Data/hora da solicitação (ISO 8601)

Status do Saque

Consultar Status do Saque

Use o withdrawalId retornado na criação para consultar o status. A consulta usa o escopo withdrawals:read e não exige IP autorizado nem x-withdrawal-secret:

curl -X GET "https://api.activepayments.com.br/api/v1/withdrawals/a1b2c3d4-e5f6-7890-abcd" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY"

{
  "success": true,
  "data": {
    "withdrawalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "100.00",
    "fee": "2.00",
    "netAmount": "100.00",
    "totalDebited": "102.00",
    "status": "COMPLETED",
    "pixKey": "des***com",
    "pixKeyType": "EMAIL",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "processedAt": "2024-01-15T10:35:00.000Z",
    "gatewayTransactionId": "gateway-tx-id"
  }
}

Códigos de Erro

Webhooks de Saque

Passe o parâmetro postbackUrl na criação do saque para receber notificações automáticas quando o status mudar.

Eventos Disponíveis

Exemplo de Payload do Webhook

{
  "event": "withdrawal.completed",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "data": {
    "withdrawalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalReference": "SAQUE-12345",
    "amount": 102.00,
    "netAmount": 100.00,
    "fee": 2.00,
    "status": "completed",
    "pixKey": "email@exemplo.com",
    "pixKeyType": "EMAIL",
    "endToEnd": "E12345678202401151035abc123",
    "processedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:25:00.000Z"
  }
}

Boas Práticas

• Sempre verifique o saldo: Consulte o endpoint /v1/balance antes de solicitar saques
• Use postbackUrl: Receba notificações em tempo real sobre o status do saque
• Valide a chave PIX: Certifique-se de que a chave PIX do destinatário está correta
• Use referências únicas: Inclua uma descrição única para rastrear o saque no seu sistema
• Verifique a assinatura: Sempre valide o header X-Webhook-Signature para garantir autenticidade