Skip to main content

​
Visão geral

Antes de realizar chamadas ao endpoint de solicitação de transferência, é importante compreender os campos aceitos, os tipos de chave PIX e as regras de negócio aplicadas. Toda requisição passa por uma série de validações em cadeia — se qualquer etapa falhar, a transferência não será processada e você receberá uma resposta de erro correspondente.

​
Campos do payload

CampoTipoObrigatórioDescrição
amountintegerSimValor do saque em centavos. Mínimo: 1000 (R$ 10,00).
key_typestringNão*Tipo da chave PIX. Se omitido, assume cpf como padrão.
key_valuestringSimValor da chave PIX de destino.
Se key_type não for informado, o sistema assume cpf como padrão e valida o key_value como CPF.

​
Tipos de chave PIX aceitos

TipoFormato esperado no key_valueValidação
cpf12345678909 ou 123.456.789-09Validado algoritmicamente (dígitos verificadores).
cnpj12345678000190 ou 12.345.678/0001-90Validado algoritmicamente (dígitos verificadores).
emailusuario@email.comValidado como e-mail válido.
phone11999999999 ou +5511999999999Deve ter entre 10 e 11 dígitos (sem o +55).
randoma1b2c3d4-e5f6-7890-abcd-ef1234567890Deve ter no mínimo 32 caracteres alfanuméricos.
CPF e CNPJ podem ser enviados com ou sem formatação (pontos, traços, barras). A API aceita ambos os formatos e realiza a validação algorítmica automaticamente.

​
Fluxo de validação

As verificações abaixo são aplicadas na ordem listada. A primeira falha interrompe o processamento e retorna o erro correspondente.
1

Autenticação das credenciais

As credenciais X-Public-Key e X-Secret-Key devem estar presentes nos headers da requisição, além de serem válidas e ativas.Se as credenciais estiverem ausentes, inválidas ou inativas, a API retorna 401 Unauthorized.
{
    "error": "Credenciais inválidas",
    "message": "Chave não encontrada ou inativa"
}
2

Permissão da credencial

A credencial utilizada deve possuir permissão do tipo cashout (apenas saídas) ou all (ambas). Credenciais do tipo apenas entrada não podem solicitar transferências.Se a credencial não tiver permissão, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Esta credencial não tem permissão para realizar esta operação.",
    "data": null
}
3

Status da conta

A conta do usuário deve estar com o status approved (aprovada). Contas pendentes, em análise ou rejeitadas não podem solicitar saques.Se a conta não estiver aprovada, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Sua conta precisa estar aprovada para solicitar saques.",
    "data": null
}
4

Conta não bloqueada

A conta do usuário não pode estar bloqueada. Contas bloqueadas perdem temporariamente o acesso a todas as funcionalidades da API.Se a conta estiver bloqueada, a API retorna 403 Forbidden.
{
    "success": false,
    "message": "Sua conta está bloqueada. Entre em contato com o suporte.",
    "data": null
}
5

Validação dos campos

Os campos obrigatórios devem ser preenchidos com valores válidos. O tipo de chave PIX deve ser um dos aceitos (cpf, cnpj, email, phone, random) e o key_value deve seguir o formato correspondente. CPF e CNPJ são validados algoritmicamente.Se houver erros de validação, a API retorna 422 Unprocessable Entity com os erros detalhados por campo.
{
    "success": false,
    "message": "Erro de validação nos dados fornecidos",
    "data": {
        "errors": {
            "amount": ["O valor mínimo para saque é R$ 10,00."],
            "key_value": ["CPF inválido."],
            "key_type": ["O tipo de chave deve ser: cpf, cnpj, email, phone ou random."]
        }
    }
}
6

Valor mínimo

O valor do saque (amount) deve ser de no mínimo 1.000 centavos (R$ 10,00).Se o valor for inferior ao mínimo, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor mínimo para saque é R$ 10,00.",
    "data": null
}
7

Saldo disponível

O usuário deve ter saldo disponível suficiente para cobrir o valor solicitado. O saldo é verificado em tempo real no momento da requisição.Se o saldo for insuficiente, a API retorna 400 Bad Request com os detalhes do saldo.
{
    "success": false,
    "message": "Saldo insuficiente para saque.",
    "data": {
        "available_balance": 30000,
        "requested_amount": 50000
    }
}
8

Limite por solicitação

O valor não pode ultrapassar o limite por solicitação configurado para o usuário (se houver). Esse limite é definido individualmente por conta.Se o valor exceder o limite, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor solicitado ultrapassa o limite por solicitação de saque.",
    "data": {
        "valid": false,
        "limit": 500000,
        "requested": 600000
    }
}
9

Limite diário

O valor não pode ultrapassar o limite diário de saques restante do usuário. O limite considera a soma de todos os saques com status paid e pending realizados no dia.Se o valor exceder o limite diário restante, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor solicitado ultrapassa o limite diário de saques.",
    "data": {
        "valid": false,
        "daily_limit": 1000000,
        "withdrawn_today": 800000,
        "remaining": 200000,
        "requested": 500000
    }
}
10

Valor líquido após taxas

Após o cálculo das taxas de saque, o valor líquido que será transferido deve ser maior que R$ 0,00. Transferências que resultem em valor líquido zero ou negativo serão rejeitadas.Se o valor líquido for insuficiente, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "O valor do saque após as taxas deve ser maior que R$ 0,00.",
    "data": null
}
11

Horário de funcionamento

Dependendo da adquirente configurada, saques podem estar restritos ao horário comercial, das 09:00 às 22:00 (horário de Brasília).Se a solicitação for feita fora do horário permitido, a API retorna 400 Bad Request.
{
    "success": false,
    "message": "Saques estão disponíveis apenas das 09:00 às 22:00. Tente novamente dentro do horário.",
    "data": null
}
12

Processamento na adquirente

Se o saque for auto-aprovado, a comunicação com a adquirente de cash-out deve ser bem-sucedida para que a transferência PIX seja realizada.Se houver falha na comunicação, a API retorna 500 Internal Server Error.
{
    "success": false,
    "message": "Erro ao processar o saque. Tente novamente mais tarde.",
    "data": null
}

​
Resposta de sucesso

Se todas as validações passarem e o saque for processado com sucesso, a API retorna 201 Created com os seguintes dados:
CampoTipoDescrição
data.idstringUUID único do saque criado
data.amountintegerValor solicitado em centavos
data.liquid_amountintegerValor líquido que será transferido em centavos (após taxas)
data.pix_key_typestringTipo da chave PIX utilizada
data.pix_keystringValor da chave PIX de destino
data.statusstringStatus inicial do saque
data.created_atstringData/hora de criação no formato YYYY-MM-DD HH:mm:ss
{
    "success": true,
    "message": "Saque solicitado e processado com sucesso!",
    "data": {
        "id": "e5f6a1b2-c3d4-7890-efgh-4567890abcde",
        "amount": 50000,
        "liquid_amount": 50000,
        "pix_key_type": "cpf",
        "pix_key": "12345678909",
        "status": "pending",
        "created_at": "2026-01-29 14:58:00"
    }
}

​
Resumo dos códigos de resposta

CódigoSituação
201Saque solicitado com sucesso
400Regra de negócio violada (saldo, limites, valor, horário)
401Credenciais ausentes, inválidas ou inativas
403Sem permissão (credencial, conta não aprovada, conta bloqueada)
422Erro de validação nos dados enviados
500Erro interno ou falha na comunicação com a adquirente