Transferências
Criar Transferência
Solicite um saque (cashout) do seu saldo disponível para uma chave PIX
POST
Solicita um saque (cashout) do seu saldo disponível para uma chave PIX.
Recomendações de segurança:
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 = 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: CPFExemplo 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
- Acesse o painel do ImperiumPay Gateway
- Vá em Menu lateral > Integrações > Adicionar Webhook
- Configure a URL do seu webhook (ex:
https://seusite.com/webhook/cashout) - Em “Tipos de Notificação”, marque “Notificar Saques”
- Salve a configuração
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 processamentoCOMPLETED- Saque concluído com sucessoREJECTED- Saque rejeitadoCANCELLED- 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.- Validar a origem usando a URL configurada
- Usar HTTPS
- Validar o
userIdpara 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
iddo saque - Valide o
userIdpara 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árioTRANSFER_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 cashoutMINIMUM_VALUE- Valor abaixo do mínimo permitido (R$ 100,00)MAXIMUM_VALUE- Valor acima do máximo permitido (R$ 100.000,00)

