Skip to main content
POST
Solicita um saque (cashout) do seu saldo disponível para uma chave PIX.

Autenticação

Este endpoint requer autenticação via API Keys:
string
required
Sua chave pública da API
string
required
Sua chave privada da API

Parâmetros do Body

number
required
Valor do cashout em reais (ex: 100.50 = R100,50).Mıˊnimo:R 100,50). **Mínimo: R 100,00**. Máximo: R$ 100.000,00
string
required
Chave PIX para recebimento (entre 8 e 77 caracteres)
string
Tipo da chave PIX. Valores possíveis: CPF, CNPJ, EMAIL, PHONE, RANDOM. Padrão: CPF
O valor mínimo para transferência é R$ 100,00. Valores abaixo deste mínimo retornarão erro TRANSFER_NOT_ALLOWED.

Exemplo de Requisição

Resposta de Sucesso

integer
ID do cashout
string
Valor em reais
string
Chave PIX
string
Status do cashout (PENDING, PROCESSING, etc.)
string
Data de criação (ISO 8601)

Exemplo de Resposta

string
Valor líquido após taxas em reais
string
Tipo da chave PIX utilizada
object
Detalhamento das taxas cobradas
string
Taxa fixa em reais
string
Taxa variável em reais
string
Total de taxas em reais

Configuração de Webhooks

Para receber notificações automáticas sobre mudanças de status dos saques, você precisa configurar um webhook no painel do usuário.

Como Configurar

  1. Acesse o painel do ImperiumPay Gateway
  2. Vá em Menu lateral > Integrações > Adicionar Webhook
  3. Configure a URL do seu webhook (ex: https://seusite.com/webhook/cashout)
  4. Em “Tipos de Notificação”, marque “Notificar Saques”
  5. Salve a configuração
Sem webhook configurado, você NÃO receberá notificações automáticas de mudança de status dos saques (PROCESSING → COMPLETED/REJECTED).

Quando o Webhook é Enviado

O webhook é enviado quando o status do saque muda, após o processamento do postback do provedor BaaS (Sqala, Witetec, Transfeera, etc.). As notificações são enviadas para os seguintes status:
  • PROCESSING - Saque em processamento
  • COMPLETED - Saque concluído com sucesso
  • REJECTED - Saque rejeitado
  • CANCELLED - Saque cancelado

Formato do Payload

Campos do Payload

Segurança

Webhooks permanentes de saques não incluem assinatura HMAC. Diferente dos postbacks por transação (que usam X-Signature), os webhooks permanentes são enviados sem assinatura.
Recomendações de segurança:
  • Validar a origem usando a URL configurada
  • Usar HTTPS
  • Validar o userId para garantir que o saque pertence à sua conta
  • Implementar idempotência para evitar processamento duplicado

Exemplo de Implementação

Boas Práticas

  • Sempre retorne HTTP 200 para confirmar recebimento
  • Implemente idempotência usando o campo id do saque
  • Valide o userId para garantir segurança
  • Use HTTPS para proteger os dados em trânsito
  • Implemente retry logic no seu servidor caso a notificação falhe
  • Log todas as notificações recebidas para auditoria

Diferenças entre Webhook Permanente e Postback

Códigos de Erro

400 Bad Request

Dados inválidos. Exemplo: valor deve ser um número válido maior que zero.

401 Unauthorized

Não autorizado - API Key ou API Secret inválidos.

403 Forbidden

Cashout via API desabilitado ou usuário sem permissão. Pode retornar:
  • API_WITHDRAWAL_DISABLED_GLOBALLY - Cashout via API está desabilitado para este usuário
  • TRANSFER_NOT_ALLOWED - Transferência não permitida

422 Unprocessable Entity

Saldo insuficiente ou regras de negócio. Pode retornar:
  • INSUFFICIENT_BALANCE - Saldo insuficiente para realizar o cashout
  • MINIMUM_VALUE - Valor abaixo do mínimo permitido (R$ 100,00)
  • MAXIMUM_VALUE - Valor acima do máximo permitido (R$ 100.000,00)

500 Internal Server Error

Erro interno do servidor.