QuickPay - Gestão Completa de Saques e Destinatários (Withdrawals)

Esta documentação detalha todos os endpoints do módulo de saques do QuickPay, incluindo parâmetros de entrada, saída, regras de negócio e cenários de erro.

---

🛠 Configuração Global

Item	Valor
URL Base	{\{base_url\}}/quickpay
Autenticação	JWT Bearer Token
Headers Exigidos	Authorization: Bearer <token>, X-Account-Id: <id>

---

1. Operações de Saque

1.1 Listar Histórico de Saques

GET /withdraws

Recupera a lista paginada de todas as solicitações de saque realizadas pela conta.

Parâmetros de Consulta (Query)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
search	string	Não	Termo de busca que varre: Nome, Documento, TXID ou EndToEndId.	E123...
per_page	integer	Não	Quantidade de registros por página (Padrão: 15).	20
page	integer	Não	Número da página solicitada.	2

Resposta de Sucesso (200 OK)

Retorna um objeto paginado contendo a lista de saques.

{
    "data": [
        {
            "id": 123,
            "txid": "E123...",
            "value": 100.5,
            "status": {
                "value": "concluido",
                "title": "Pago",
                "description": ""
            },
            "document": "12345678901",
            "created_at": "2024-03-25T12:00:00Z"
        }
    ],
    "meta": { "current_page": 1, "last_page": 5, "total": 75 }
}

---

1.2 Detalhes do Saque e Transação

GET /withdraws/\{id\}

Retorna os dados detalhados de um saque específico e vincula a transação do extrato (se disponível).

Parâmetros de Caminho (Path)

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

Resposta de Sucesso (200 OK)

{
    "data": {
        "id": 123,
        "unique_hash": "hash...",
        "name": "NOME DO FAVORECIDO",
        "document": "12345678901",
        "bank_code": "001",
        "branch": "0001",
        "account_number": "12345-6",
        "account_type": "CORRENTE",
        "status": {
            "value": "concluido",
            "title": "Pago",
            "description": "..."
        },
        "value": 100.5,
        "txid": "E123...",
        "endtoendid": "E456...",
        "created_at": "..."
    },
    "transaction": {
        "id": 500,
        "datetime": "2024-03-25 12:00:05",
        "value": -100.5,
        "balance": 1400.0,
        "type": { "id": 3, "slug": "pix-out", "name": "Pix de Saída" }
    }
}

---

1.3 Iniciar Saque (Preparação / Lookup)

POST /withdraws

Valida uma chave Pix no DICT (Diretório Central de Chaves), calcula o saldo disponível e verifica destinatários salvos.

Parâmetros de Entrada (Body)

Parâmetro	Tipo	Obrigatório	Descrição
keypix	string	Sim	Chave Pix de destino (CPF, CNPJ, Email, Telefone ou EVP).
value	numeric	Não	Valor pretendido. Realiza pré-checagem de saldo.
message	string	Não	Descrição interna da transação (máx 255).

Cenários e Regras:

1. Sucesso (201 Created): Retorna os dados do recebedor (Nome e Documento mascarado) e o internal_id.
2. Saldo Insuficiente (422): Se o value + taxa for maior que o saldo líquido da conta.
3. Chave Não Encontrada (404): Se a chave Pix não estiver registrada no Banco Central.
4. Duplicidade (422): Se houver tentativa de saque para o mesmo destino e valor na última 1 hora.

---

1.4 Confirmar Saque Pix (Efetivação)

POST /withdraws/confirm

Finaliza a transferência Pix. Exige PIN de segurança.

Parâmetros de Entrada (Body)

Parâmetro	Tipo	Obrigatório	Descrição
internal_id	integer	Sim	ID retornado no passo de Início (1.3).
keypix	string	Sim	Confirmação da chave Pix de destino.
value	numeric	Sim	Valor exato a ser transferido (mín 0.01).
pin	string	Sim	PIN de segurança da conta (6 dígitos numéricos).
message	string	Não	Mensagem enviada ao recebedor (máx 140 carac.).

Cenários de Resposta:

• Sucesso (201): {"success": true, "data": {"txid": "...", "endtoendid": "..."}, "message": "..."}
• PIN Inválido (403): Se o PIN estiver incorreto.
• Saque Inválido (422): Se o internal_id já foi usado ou não pertence à conta.
• Saldo Insuficiente (422): Re-checagem final de fundos no momento da execução.

---

1.5 Saque via Dados Bancários (Manual)

POST /withdraws/bank

Efetiva uma transferência informando manualmente Banco, Agência e Conta.

Parâmetros de Entrada (Body)

Parâmetro	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor da transferência (mín 0.01).
bank_code	string	Sim	Código COMPE (3 dígitos) ou ISPB do banco.
agency	string	Sim	Agência de destino (sem dígito).
account	string	Sim	Conta de destino com dígito (ex: 12345-6).
beneficiary_name	string	Sim	Nome completo do favorecido.
beneficiary_document	string	Sim	CPF ou CNPJ do favorecido.
pin	string	Sim	PIN de segurança da conta.
message	string	Não	Mensagem opcional.

---

2. Agenda e Favoritos (Recipients)

Gestão dos contatos frequentes e histórico de destinatários.

2.1 Listar Todos os Contatos

GET /withdraws/recipients

Lista paginada de todos os clientes que já receberam pagamentos da conta.

• Query search: Filtra por nome, documento, banco ou conta.

2.2 Listar Favoritos (Frequentes)

GET /withdraws/recipients/frequent

Retorna os 10 destinatários que mais receberam transferências da conta nos últimos meses.

• Ordenação: Por contagem de uso (count) decrescente.

---

📋 Tabela de Referência: Status de Saque

Status (WithdrawStatusEnum)	Valor (DB)	Titulo (UI)	Significado Técnicos
AWAITING	aguardando	Aguardando	Registro criado, aguardando confirmação do PIN.
COMPLETED	concluido	Pago	Transferência liquidada instantaneamente.
ERROR	erro	Falha	Houve erro na validação ou rede bancária.
AWAITING_PAYMENT	awaiting_payment	Aguardando	Saque gerado automaticamente via .
PROCESSING_PAYMENT	processing_payment	Processando	Saque em fila de processamento bancário.
PAID	paid	Pago	Legado de saques já liquidados via automação.

NOTE

O sistema suporta mapeamento automático de status numéricos legados (0, 1, 200) para os títulos correspondentes acima, garantindo compatibilidade com registros antigos.

---

🔐 Regras Gerais de Segurança e Negócio

1. Proteção de PIN: A conta bloqueia qualquer tentativa de saque se o PIN informado não coincidir com o hash salvo no banco.
2. Proteção Anti-Spam/Duplicidade: O sistema armazena o document do recebedor e o value. Se houver uma requisição idêntica em menos de 1 hora, a API retornará erro 422 para prevenir cliques duplos.
3. Cálculo de Transação: Todo saque bem-sucedido gera duas transações no extrato:
   • Uma do tipo pix-out (Valor negativo do saque).
   • Uma do tipo taxa (Valor conforme tax_pix_out configurado na conta).
4. Cadastro Automático: Ao concluir um saque para um novo CPF/CNPJ, o sistema cria automaticamente um registro em clients e pix_recipients para facilitar futuras transferências.

---

Status de Saque (Withdrawals)

[GET] /enums/withdraws/status

Retorna os status de processamento de saques e transferências realizadas pelo QuickPay.

Response (200 OK)

[
    {
        "value": "aguardando",
        "title": "Aguardando",
        "description": "O saque está aguardando confirmação."
    },
    {
        "value": "concluido",
        "title": "Pago",
        "description": "O saque foi processado e pago com sucesso."
    },
    {
        "value": "erro",
        "title": "Falha",
        "description": "O saque falhou durante o processamento."
    },
    {
        "value": "awaiting_payment",
        "title": "Aguardando",
        "description": "O saque está aguardando o processamento de pagamento."
    },
    {
        "value": "processing_payment",
        "title": "Processando",
        "description": "O saque está sendo processado."
    }
]

Última atualização: 25/03/2026 - Versão Completa (Parameters & Scenarios)