Documentação da API de Saques (Pix Out & Transferências)

A API de Saques permite que as contas realizem saídas financeiras via Pix ou Transferências Bancárias tradicionais. Possui um processo de verificação em duas etapas, armazenamento de dados para favorecidos frequentes e medidas de segurança robustas, incluindo validação de PIN e proteção contra transações duplicadas.

IMPORTANT

Proteção contra Duplicidade: Qualquer tentativa de enviar o mesmo valor para o mesmo destinatário (chave ou documento) dentro de uma janela de 1 hora será bloqueada para evitar pagamentos duplos acidentais.

---

🛠 Configuração Global

Requisito	Valor
URL Base
Estratégia de Autenticação	JWT Bearer Token
Headers Obrigatórios	Authorization: Bearer <token>, account: <id>, Content-Type: application/json

---

1. Listar Destinatários Frequentes

GET /recipients/frequent

Retorna uma lista dos 10 destinatários mais frequentes da conta atual, com base no histórico de transações.

Parâmetros de Consulta (Query)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
search	string	Não	Filtrar por nome, documento ou chave Pix. Insensível a maiúsculas/minúsculas e ignora máscaras em campos numéricos.	123.456

Resposta de Sucesso (200 OK)

{
    "success": true,
    "data": [
        {
            "id": 1,
            "account_id": 10,
            "pix_key": "financeiro@exemplo.com",
            "name": "JOÃO SILVA",
            "document": "12345678900",
            "bank_name": "SICOOB",
            "bank_code": "756",
            "branch": "0001",
            "account": "123456-7",
            "account_type": "CORRENTE",
            "count": 15,
            "last_used_at": "2024-03-07T14:46:37Z"
        }
    ],
    "message": "Destinatários frequentes recuperados com sucesso."
}

---

2. Listar Solicitações de Saque

GET /recipients

Recupera uma lista paginada de todas as tentativas de saque (pendentes, concluídas e falhas).

Parâmetros de Consulta (Query)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
page	int	Não	Número da página para paginação.	1
per_page	int	Não	Itens por página (Padrão: 15).	20
search	string	Não	Filtrar por nome, documento, TXID ou EndToEndId. Insensível a maiúsculas e ignora máscaras para documentos.	E123...

Resposta de Sucesso (200 OK)

{
    "data": [
        {
            "id": 123,
            "txid": "E123456...",
            "value": 100.50,
            "status": "concluido",
            "document": "12345678900",
            "created_at": "2024-03-07T14:46:37Z"
        }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
    "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "...", "per_page": 15, "to": 1, "total": 1 }
}

---

3. Obter Detalhes do Saque

GET /recipients/{id}

Recupera os detalhes completos de um registro de saque específico e sua transação de extrato associada.

Parâmetros de Caminho (Path)

Parâmetro	Tipo	Obrigatório	Descrição
id	int	Sim	O ID interno do registro de saque.

Resposta de Sucesso (200 OK)

{
    "data": {
        "id": 123,
        "txid": "E123...",
        "value": 100.50,
        "status": "concluido",
        "document": "123...",
        "json": { ... }
    },
    "transaction": {
        "id": 500,
        "type_id": 2,
        "value": -100.50,
        "balance": 950.00,
        "datetime": "2024-03-07 14:46:37"
    }
}

---

4. Preparar / Iniciar Saque Pix

POST /recipients

Valida uma chave Pix, verifica dados de destinatários existentes e prepara o registro de saque.

TIP

Este endpoint retorna o Saldo da Conta. Use-o para informar ao usuário se ele tem fundos suficientes antes de digitar o PIN.

Corpo da Requisição (Body)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
keypix	string	Sim	Chave Pix (CPF, CNPJ, E-mail, Telefone ou EVP).	usuario@email.com
value	float	Não	Valor inicial opcional. Pode ser definido/atualizado na confirmação.	50.00

Resposta de Sucesso (200 OK)

{
    "data": {
        "txid": "E7132876920260...",
        "data": "2026-03-07 18:08:45",
        "endToEndId": "E7132876...",
        "valor": 0,
        "pagador": {
            "nome": "FASTGIVRMONEY",
            "documento": "05796581000133",
            "conta": {
                "numero": "...",
                "digito": "...",
                "tipoConta": "....",
                "agencia": "..."
            },
            "banco": {
                "nome": "BANCO DO BRASIL",
                "codigo": "...."
            }
        },
        "recebedor": {
            "nome": "Frederico",
            "documento": "***33838***",
            "conta": {
                "numero": "",
                "digito": "",
                "tipo": "",
                "agencia": ""
            },
            "banco": {
                "nome": "",
                "codigo": ""
            }
        },
        "internal_id": 3581,
        "account_balance": 1318.97,
        "stored_recipient": {
            "name": "NOME DO FAVORECIDO",
            "bank_name": "BB",
            "pix_key": "usuario@email.com",
            ...
        }
    }
}

Erros Comuns

• 422 Unprocessable Entity: Chave Pix ou valor inválido.
• 422 Unprocessable Entity: "Já foi iniciado um saque com este valor e destino na última 1 hora."

---

5. Executar Saque Pix (Confirmação)

POST /api/pix/withdraw

Finaliza a transferência Pix. Requer o PIN do usuário para autorização.

CAUTION

Validação de PIN: A conta deve ter um PIN configurado. Se o PIN estiver incorreto, a transação é rejeitada imediatamente.

Corpo da Requisição (Body)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
internal_id	int	Sim	ID retornado pelo passo "Preparar Saque".	124
keypix	string	Sim	A chave Pix de destino.	usuario@email.com
value	float	Sim	O valor final a ser enviado.	50.00
pin	string	Sim	PIN de segurança de 6 dígitos.	123456
message	string	Não	Descrição da transação (Sicoob: máx 140 caracteres).	Presente

Resposta de Sucesso (201 Created)

{
    "success": true,
    "data": {
        "txid": "E123456...",
        "endtoendid": "E123456...",
        "value": 50.00,
        "date": "07-03-2024 16:30:00"
    },
    "message": "Transferência Pix realizada com sucesso"
}

Erros de Lógica

• 403 Forbidden: {"message": "PIN inválido."}
• 422 Unprocessable Entity: {"errors": {"value": ["Saldo insuficiente."]}}
• 422 Unprocessable Entity: {"errors": {"value": ["Já existe uma transação concluída com este mesmo valor... na última 1 hora."]}}

---

6. Saque via Transferência Bancária (Manual)

POST /api/pix/withdraw-bank

Executa uma transferência usando dados bancários completos (Agência/Conta). Use quando o favorecido não possui chave Pix.

Corpo da Requisição (Body)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
amount	float	Sim	Valor a transferir.	150.00
bank_code	string	Sim	Banco de destino (ISPB ou COMPE).	001
agency	string	Sim	Agência de destino (sem dígito).	1234
account	string	Sim	Conta de destino com dígito.	56789-0
beneficiary_name	string	Sim	Nome completo do favorecido.	MARIA SILVA
beneficiary_document	string	Sim	CPF ou CNPJ do favorecido.	12345678900
pin	string	Sim	PIN de segurança de 6 dígitos.	123456
message	string	Não	Descrição para a transferência.	Aluguel

Resposta de Sucesso (200 OK)

{
    "data": {
        "id": 125,
        "status": "concluido",
        "value": 150.00,
        "txid": "E123...",
        ...
    },
    "transaction": {
        "id": 501,
        "value": -150.00,
        "balance": 800.00
    }
}

---

🛑 Códigos de Erro Comuns

Código	Tipo	Significado
400	Bad Request	Headers ausentes ou JSON malformado.
403	Forbidden	PIN inválido ou Permissão negada.
404	Not Found	O recurso (ID do Saque) não existe.
422	Validation Error	Os dados enviados não passaram na validação (Verifique o campo errors).
500	Server Error	Falha crítica no provedor bancário ou banco de dados.

---

Última modificação: 07/03/2026