QuickPay — API Descontinuada

DANGER

Atenção: Todos os endpoints desta página estão descontinuados e mantidos apenas por compatibilidade. Não os utilize em novas integrações. Consulte as seções recomendadas indicadas em cada endpoint.

---

Autenticação

Todos os endpoints exigem os seguintes cabeçalhos:

Header	Exemplo	Obrigatório
Authorization	Bearer <token>	Sim
X-Account-Id	123	Sim
Content-Type	application/json	Sim (POST/PUT)

URL Base: {base_url}/quickpay

---

1. Verificação do Módulo

GET /quickpay

Retorna uma string de verificação. Sem utilidade prática.

Response (200 OK)

"quickpay"

---

2. Pix In — Recebimento

2.1 Listar Pix Gerados

GET /quickpay/pix/list

Use a documentação de Pix atualizada como referência para novas integrações.

Lista os QR Codes Pix gerados pela conta. Aceita dois modos de uso: listagem paginada ou consulta por ID.

Modo 1 — Listagem paginada

Query Params

Parâmetro	Tipo	Obrigatório	Descrição
per_page	integer	Não	Itens por página (padrão: 15)
page	integer	Não	Número da página (padrão: 1)

Response (200 OK)

{
  "data": [
    {
      "id": 150,
      "txid": "abc123px",
      "qrcode": "000201010212260014br.gov.bcb.pix...",
      "value": 100.50,
      "status": "pending",
      "created_at": "2024-12-10T15:00:00.000000Z",
      "image": "data:image/png;base64,..."
    }
  ],
  "current_page": 1,
  "last_page": 5,
  "per_page": 15,
  "total": 73
}

Modo 2 — Consulta individual

Ao passar txid ou id como query param, retorna um único Pix com suas transações associadas.

Query Params

Parâmetro	Tipo	Descrição
txid	string	ID do Pix
id	integer	Alias de txid

Response (200 OK)

{
  "id": 150,
  "txid": "abc123px",
  "qrcode": "000201010212260014br.gov.bcb.pix...",
  "value": 100.50,
  "status": "pending",
  "image": "data:image/png;base64,...",
  "transactions": [
    {
      "id": 200,
      "value": 100.50,
      "datetime": "2024-12-10T15:05:00.000000Z"
    }
  ]
}

Response (404)

{ "success": false, "message": "Pix não encontrado para esta conta.", "data": null }

---

2.2 Criar QR Code Pix Dinâmico

POST /quickpay/pix/createPOST /quickpay/pix/qrcodePOST /quickpay/pix/qrcode-fixo

Os três caminhos são equivalentes e fazem a mesma operação.

Gera um novo QR Code Pix com valor definido.

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor em BRL (mínimo configurado na conta, geralmente R$ 1,00)
webhook	url	Não	URL para receber notificações de pagamento
name	string	Não	Nome do pagador (máx 100)
email	email	Não	E-mail do pagador (máx 100)
document	string	Não	CPF ou CNPJ do pagador
phone	string	Não	Telefone do pagador

Response (201 Created)

{
  "success": true,
  "pix": {
    "id": 151,
    "txid": "def456px",
    "value": 100.50,
    "qrcode": "000201010212260014br.gov.bcb.pix...",
    "created_at": "2024-12-26T16:00:00.000000Z",
    "image": "data:image/png;base64,..."
  }
}

Regras:

• O valor mínimo aceito é definido pela configuração da conta
• Quando name, email e document são fornecidos juntos, o pagador é associado à cobrança

Erros:

• 422 — campo inválido (valor abaixo do mínimo, URL inválida)
• 500 — falha na comunicação com a instituição bancária

---

2.3 QR Code Fixo da Conta

GET /quickpay/pix/image

Retorna o payload EMV do QR Code estático da conta. Não gera cobrança — o pagador define o valor.

Response (200 OK)

{
  "success": true,
  "data": {
    "payload": "000201010211260014br.gov.bcb.pix0114+5511999999999..."
  }
}

Regras:

• O QR Code estático aceita qualquer valor definido pelo pagador no momento do pagamento
• Não use este endpoint para cobranças com valor específico — prefira o endpoint 2.2

---

2.4 Consultar Pix por TXID

GET /quickpay/pix/{txid}

Retorna os dados de um Pix específico.

Path Params

Parâmetro	Tipo	Descrição
txid	string	TXID do Pix

Response (200 OK)

{
  "txid": "abc123px",
  "image": "data:image/png;base64,...",
  "qrcode": "000201010212...",
  "status": "pending",
  "value": 100.50,
  "name": "João da Silva",
  "email": "joao@email.com",
  "document": "12345678901",
  "created_at": "2024-12-10T15:00:00.000000Z",
  "updated_at": "2024-12-10T15:00:00.000000Z"
}

Response (404)

{ "success": false, "message": "Pix não encontrado para esta conta.", "data": null }

---

3. Saques — Pix Out

3.1 Listar Saques

GET /quickpay/withdraws

Retorna o histórico paginado de saques realizados pela conta.

Query Params

Parâmetro	Tipo	Obrigatório	Descrição
search	string	Não	Busca por nome, TXID, EndToEndId ou chave Pix
per_page	integer	Não	Itens por página (padrão: 15)
page	integer	Não	Página atual

Response (200 OK)

{
  "data": [
    {
      "id": 123,
      "txid": "E123...",
      "endtoendid": "E456...",
      "value": 100.50,
      "status": { "value": "concluido", "title": "Pago", "description": "" },
      "name": "NOME DO FAVORECIDO",
      "document": "12345678901",
      "key_pix": "joao@email.com",
      "bank_code": "341",
      "branch": "0001",
      "account_number": "12345-6",
      "account_type": "CORRENTE",
      "message": "Pagamento serviços",
      "created_at": "2024-03-25T12:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 75 }
}

---

3.2 Detalhar Saque

GET /quickpay/withdraws/{id}

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

Path Params

Parâmetro	Tipo	Descrição
id	integer	ID do saque

Response (200 OK)

{
  "data": {
    "id": 123,
    "name": "NOME DO FAVORECIDO",
    "document": "12345678901",
    "bank_code": "341",
    "branch": "0001",
    "account_number": "12345-6",
    "account_type": "CORRENTE",
    "status": { "value": "concluido", "title": "Pago" },
    "value": 100.50,
    "txid": "E123...",
    "endtoendid": "E456...",
    "key_pix": "joao@email.com",
    "message": "Pagamento serviços",
    "created_at": "2024-03-25T12:00:00Z"
  },
  "transaction": {
    "id": 500,
    "datetime": "2024-03-25 12:00:05",
    "value": -100.50,
    "balance": 1400.00,
    "type": { "slug": "pix-out", "name": "Pix de Saída" }
  }
}

Regras:

• O campo transaction pode ser null se o extrato não possuir correspondência para este saque
• Retorna 404 se o saque não pertencer à conta autenticada

---

3.3 Iniciar Saque — Lookup da Chave Pix

POST /quickpay/withdraws

Consulta uma chave Pix no Banco Central e prepara o registro de saque. Não realiza a transferência. Use este endpoint para exibir os dados do destinatário antes da confirmação.

Request Body

Campo	Tipo	Obrigatório	Descrição
keypix	string	Sim	Chave Pix de destino (CPF, CNPJ, e-mail, telefone ou chave aleatória)
value	numeric	Não	Valor pretendido — usado para verificar o saldo disponível
message	string	Não	Descrição da transferência (máx 255)

Response — Sucesso

{
  "data": {
    "internal_id": 124,
    "name": "NOME BENEFICIÁRIO",
    "document": "123***78901",
    "bank_code": "341",
    "branch": "0001",
    "account_number": "98765-4",
    "account_type": "CORRENTE",
    "key_pix": "joao@email.com",
    "account_balance": 1500.00
  }
}

Response — Solicitação duplicada (200 OK)

Quando já existe um saque aguardando confirmação para o mesmo destinatário e valor na última 1 hora, a API reutiliza o registro existente:

{
  "data": {
    "internal_id": 120,
    "account_balance": 1500.00,
    "stored_recipient": { ... }
  }
}

Response (404) — Chave não encontrada

{ "success": false, "message": "A chave Pix pesquisada não existe." }

Regras:

• CPFs e CNPJs têm formatação removida automaticamente antes da consulta
• O campo internal_id retornado é obrigatório para o passo de confirmação (3.4)
• Se a requisição for duplicada na última 1 hora (mesmo destinatário e valor), o sistema retorna o registro existente em vez de criar um novo

---

3.4 Confirmar Saque Pix

POST /quickpay/withdraws/confirm

Finaliza a transferência Pix. Exige PIN de segurança. Este é o passo que efetivamente debita o saldo.

Request Body

Campo	Tipo	Obrigatório	Descrição
internal_id	integer	Sim	ID retornado no passo 3.3
keypix	string	Sim	Confirmação da chave Pix de destino
value	numeric	Sim	Valor exato a transferir (mín R$ 0,01)
pin	string	Sim	PIN de segurança da conta
message	string	Não	Mensagem enviada ao recebedor (máx 140 caracteres)

Response (201) — Sucesso

{
  "success": true,
  "message": "Transferência Pix realizada com sucesso",
  "data": {
    "txid": "E789...",
    "endtoendid": "E101...",
    "value": 100.50,
    "receiver_name": "NOME BENEFICIÁRIO",
    "receiver_document": "12345678901",
    "receiver_bank_name": "ITAÚ UNIBANCO",
    "receiver_agency": "0001",
    "receiver_account": "98765-4",
    "receiver_account_type": "CORRENTE"
  }
}

Response (403) — PIN inválido

{ "success": false, "message": "PIN inválido.", "data": [] }

Regras:

• O PIN é validado antes de qualquer operação bancária. PIN incorreto retorna 403 imediatamente
• Após transferência bem-sucedida, aparecem duas entradas no extrato: o valor do saque e a taxa da operação
• O destinatário é salvo automaticamente para facilitar transferências futuras

---

3.5 Saque via Dados Bancários

POST /quickpay/withdraws/bank

Transfere Pix informando agência, conta e banco manualmente. Operação única (sem etapa de lookup). Exige PIN de segurança.

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor da transferência em BRL (mín R$ 0,01)
bank_code	string	Sim	Código COMPE (3 dígitos) ou ISPB do banco
agency	string	Sim	Agência sem dígito verificador
account	string	Sim	Conta com dígito verificador (ex: 12345-6)
beneficiary_name	string	Sim	Nome completo do favorecido
beneficiary_document	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos)
pin	string	Sim	PIN de segurança da conta
message	string	Não	Mensagem opcional

Response (200 OK)

{
  "data": {
    "id": 125,
    "txid": "E202...",
    "endtoendid": "E303...",
    "value": 200.00,
    "status": { "value": "concluido", "title": "Pago" },
    "name": "NOME FAVORECIDO",
    "document": "12345678901",
    "bank_code": "341",
    "branch": "0001",
    "account_number": "55555-5"
  },
  "transaction": {
    "id": 501,
    "value": -200.00,
    "balance": 1300.00,
    "type": { "slug": "pix-out" }
  }
}

Regras:

• O bank_code deve corresponder a uma instituição financeira válida no sistema
• Diferente do fluxo com chave Pix, esta operação não tem etapa de lookup prévia

---

3.6 Listar Destinatários

GET /quickpay/withdraws/recipients

Retorna clientes que já receberam transferências da conta, com suas chaves Pix cadastradas.

Query Params

Parâmetro	Tipo	Descrição
search	string	Busca por nome, chave Pix, banco, agência, conta ou documento
per_page	integer	Itens por página (padrão: 15)

Response (200 OK)

{
  "data": [
    {
      "id": 10,
      "name": "NOME CLIENTE",
      "document": "12345678901",
      "email": "cliente@email.com",
      "pix_recipients": [
        {
          "id": 5,
          "pix_key": "joao@email.com",
          "bank_name": "ITAÚ",
          "bank_code": "341",
          "branch": "0001",
          "account": "12345-6",
          "account_type": "CORRENTE",
          "count": 5,
          "last_used_at": "2024-12-25T10:00:00Z"
        }
      ]
    }
  ],
  "meta": { "current_page": 1, "last_page": 2, "total": 18 }
}

---

3.7 Destinatários Frequentes

GET /quickpay/withdraws/recipients/frequent

Retorna os 10 destinatários mais utilizados pela conta.

Query Params

Parâmetro	Tipo	Descrição
search	string	Busca por nome, chave Pix ou documento

Response (200 OK)

{
  "success": true,
  "message": "Destinatários frequentes recuperados com sucesso.",
  "data": [
    {
      "id": 5,
      "pix_key": "joao@email.com",
      "name": "NOME FAVORECIDO",
      "document": "12345678901",
      "bank_name": "ITAÚ",
      "bank_code": "341",
      "count": 12,
      "last_used_at": "2024-12-25T10:00:00Z"
    }
  ]
}

Regras:

• Retorna no máximo 10 resultados, ordenados por frequência de uso

---

3.8 Destinatário por ID

GET /quickpay/withdraws/recipients/frequent/{id}

Retorna os dados de um destinatário específico.

Path Params

Parâmetro	Tipo	Descrição
id	integer	ID do destinatário

Response (200 OK)

{
  "success": true,
  "message": "Destinatário recuperado com sucesso.",
  "data": {
    "id": 5,
    "pix_key": "joao@email.com",
    "name": "NOME FAVORECIDO",
    "document": "12345678901",
    "bank_name": "ITAÚ",
    "bank_code": "341",
    "branch": "0001",
    "account": "12345-6",
    "account_type": "CORRENTE",
    "count": 12,
    "last_used_at": "2024-12-25T10:00:00Z"
  }
}

---

4. Pix Out — Endpoints Descontinuados (Não Usar)

DANGER

Os três endpoints abaixo estão descontinuados e com problemas conhecidos. Não os utilize. Use os endpoints da seção 3 (Saques) ou seção 8 (Pix Out) como substitutos.

4.1 POST /quickpay/saida-sicred

Substituto: POST /quickpay/withdraws + POST /quickpay/withdraws/confirm

Problema: Integração direta com configuração bancária fixa — não suporta múltiplas contas. Descontinuado.

Request Body

Campo	Tipo	Obrigatório	Descrição
mount	numeric	Sim	Valor do Pix (atenção: o campo se chama mount, não amount)
keyPix	string	Sim	Chave Pix do beneficiário (máx 99)
documentoBeneficiario	string	Sim	CPF ou CNPJ do beneficiário (máx 99)
message	string	Não	Mensagem Pix (máx 99)

---

4.2 POST /quickpay/pix-out/dataBank

Substituto: POST /quickpay/pixout/pix-databank

Problema: Bug conhecido — o valor da transação gerada no extrato fica incorreto. Não usar.

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor da transferência
beneficiary_name	string	Sim	Nome do beneficiário
beneficiary_document	string	Sim	CPF ou CNPJ
bank_code	string	Sim	Código do banco
branch	string	Sim	Agência
account	string	Sim	Número da conta
account_type	string	Sim	CORRENTE, POUPANCA, SALARIO ou PAGAMENTO
mensagem	string	Não	Mensagem opcional
payment_date	date	Não	Data de pagamento agendado

---

4.3 POST /quickpay/boleto-saida-sicred

DANGER

Não implementado. Este endpoint retorna erro 500. Não utilize.

---

5. Boleto — Paths Legados (/boleto/)

WARNING

Os paths abaixo usam /boleto/ (sem 's'). O caminho atual e recomendado é /boletos/ (seção 6). Ambos funcionam, mas os paths legados serão removidos em versão futura.

Endpoint legado	Substituto
GET /quickpay/boleto/list	GET /quickpay/boletos
POST /quickpay/boleto/create	POST /quickpay/boletos
GET /quickpay/boleto/{txid}	GET /quickpay/boletos/{txid}
POST /quickpay/boleto/cancel	POST /quickpay/boletos/cancel
POST /quickpay/boleto/pdf/{txid}	POST /quickpay/boletos/{txid}/pdf
DELETE /quickpay/boleto/{txid}	DELETE /quickpay/boletos/{txid}

Parâmetros, respostas e regras são idênticos. Consulte a seção 6 para a especificação completa.

---

6. Boleto — Paths Atuais (/boletos/)

NOTE

Estes endpoints fazem parte do mesmo arquivo de rotas descontinuado, mas são os caminhos recomendados para boletos. A referência completa está em QuickPay — Boletos.

6.1 Listar Boletos

GET /quickpay/boletos

Query Params

Parâmetro	Tipo	Descrição
page	integer	Página atual (padrão: 1)
per_page	integer	Itens por página (padrão: 100)
status	integer	Filtro por código de status
created_at_start	date	Data inicial de criação (Y-m-d)
created_at_end	date	Data final de criação (Y-m-d)
payment_date_start	date	Data inicial de pagamento (Y-m-d)
payment_date_end	date	Data final de pagamento (Y-m-d)
updated_at_start	date	Data inicial de atualização (Y-m-d)
updated_at_end	date	Data final de atualização (Y-m-d)
search	string	Busca por nome, e-mail, documento ou TXID

Response (200 OK)

{
  "data": [
    {
      "id": 85,
      "status": 1,
      "status_label": "Pago",
      "txid": "bol_def456",
      "name": "Maria Santos",
      "email": "maria@email.com",
      "document": "12345678901",
      "value": "250.00",
      "expired": "2024-12-30",
      "barcode": "...",
      "digitableLine": "...",
      "ourNumber": "12345678",
      "yourNumber": "000001",
      "paid_amount": 250.00,
      "payment_date": "2024-12-15",
      "pix": [
        { "id": 10, "status": 1, "txid": "...", "qrcode": "...", "value": "250.00" }
      ]
    }
  ],
  "meta": { "current_page": 1, "per_page": 100, "total": 1, "last_page": 1 }
}

---

6.2 Criar Boleto

POST /quickpay/boletos

Gera um boleto bancário, opcionalmente com QR Code Pix vinculado (Bolepix).

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor nominal em BRL
expiration_date	date	Sim	Data de vencimento (Y-m-d)
name	string	Sim	Nome do pagador
email	email	Sim	E-mail do pagador
document	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos)
webhook	url	Não	URL para notificações de mudança de status
hasPix	boolean	Não	true gera QR Code Pix junto ao boleto (Bolepix)
hasPDF	boolean	Não	true gera o PDF do boleto imediatamente
late_fee	numeric	Não	Multa pós-vencimento
late_fee_type	string	Não	Tipo da multa: ABSOLUTE ou PERCENTAGE
amount_rate	numeric	Não	Juros mensais
type_rate	string	Não	Tipo dos juros: ABSOLUTE ou PERCENTAGE
discount	numeric	Não	Valor ou percentual de desconto
days_discount	integer	Não	Dias antes do vencimento para aplicar o desconto
type_discount	string	Não	Tipo do desconto: ABSOLUTE ou PERCENTAGE
phone	string	Não	Telefone do pagador
address	object	Não	Endereço: { street, number, city, state, zipcode }
informative	string	Não	Texto informativo exibido no boleto

Response (200 OK)

{
  "success": true,
  "message": "Boleto Gerado com sucesso",
  "data": {
    "txid": "bol_abc123",
    "status": 0,
    "value": 250.00,
    "name": "João da Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "barcode": "34191.75301 24945.450801 30600.000000 1 98180000025000",
    "digitableLine": "341917530124945450801306000000001981800002500",
    "expired": "2024-12-30",
    "ourNumber": "12345678",
    "yourNumber": "000001",
    "pix": {
      "txid": "pixabc123",
      "value": 250.00,
      "qrcode": "000201010212...",
      "image": "data:image/png;base64,..."
    },
    "pdf_path": "/storage/boletos/bol_abc123.pdf"
  }
}

Regras:

• Com hasPix: true, o boleto recebe um QR Code Pix alternativo para pagamento (Bolepix)
• Com hasPDF: true, o link do PDF já vem na resposta em pdf_path
• Multa, juros e desconto são todos opcionais
• Em caso de falha, nenhum dado é persistido

Erros:

• 400 — erro retornado pela instituição bancária
• 422 — campo inválido ou ausente

---

6.3 Consultar Boleto

GET /quickpay/boletos/{txid}

Path Params

Parâmetro	Tipo	Descrição
txid	string	TXID do boleto

Retorna os dados completos do boleto. Retorna 404 se o TXID não pertencer à conta.

---

6.4 Cancelar Boleto(s)

POST /quickpay/boletos/cancel

Cancela um ou mais boletos. Processa cada TXID individualmente — erros em um não cancelam os demais.

Request Body

Campo	Tipo	Obrigatório	Descrição
txid	string	Condicional*	TXID para cancelamento unitário
txids	array	Condicional*	Lista de TXIDs para cancelamento em lote

* Pelo menos um dos campos é obrigatório.

Exemplo (lote)

{ "txids": ["bol_123", "bol_456"] }

Response (200 OK)

{
  "success": true,
  "message": "Processamento de cancelamento concluído",
  "data": {
    "bol_123": { "success": true,  "message": "Boleto cancelado com sucesso" },
    "bol_456": { "success": false, "message": "Boleto já está pago e não pode ser cancelado" }
  }
}

Regras:

• Boletos com status Pago não podem ser cancelados
• Se a comunicação com o banco falhar, o boleto ainda é marcado como cancelado localmente
• O Pix vinculado (Bolepix) também é cancelado junto

---

6.5 URL do PDF do Boleto

POST /quickpay/boletos/{txid}/pdf

Retorna os links de acesso ao PDF do boleto.

Path Params

Parâmetro	Tipo	Descrição
txid	string	TXID do boleto

Response (200 OK)

{
  "success": true,
  "message": "PDF gerado com sucesso",
  "data": {
    "pdf_url": "/storage/boletos/boleto_bol_abc123.pdf",
    "pdf_path": "/storage/boletos/boleto_bol_abc123.pdf",
    "pdf_url_full": "https://api.fastgivr.com/storage/boletos/boleto_bol_abc123.pdf"
  }
}

Regras:

• O PDF precisa ter sido gerado no momento da criação (via hasPDF: true). Este endpoint apenas retorna a URL — não gera o PDF novamente.

---

6.6 Cancelar Boleto (DELETE)

DELETE /quickpay/boletos/{txid}

Equivalente ao cancelamento unitário (6.4), usando o método HTTP DELETE.

Path Params

Parâmetro	Tipo	Descrição
txid	string	TXID do boleto

Response (200 OK)

{ "success": true, "message": "Boleto deletado com sucesso.", "data": null }

Regras:

• Falhas na comunicação com o banco são ignoradas — o boleto é cancelado localmente de qualquer forma
• O Pix vinculado (Bolepix) também é cancelado

---

7. Pagamento de Boleto Externo

Endpoints para pagar boletos de terceiros debitando o saldo da conta. O fluxo é obrigatoriamente em 2 etapas: consultar o boleto e depois confirmar o pagamento.

7.1 Listar Pagamentos de Boleto (Saída)

GET /quickpay/boleto/payments

Lista todos os boletos externos consultados ou pagos pela conta.

Query Params

Parâmetro	Tipo	Descrição
per_page	integer	Itens por página (padrão: 15)
status	string	Filtro por status do pagamento

Response (200 OK)

{
  "data": [
    {
      "id": 10,
      "barcode": "00190500954014481606...",
      "value": 150.00,
      "status": "completed",
      "due_date": "2024-12-30",
      "paid_at": "2024-12-15T10:00:00Z",
      "txid": "idPagamento123",
      "created_at": "2024-12-14T09:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "total": 5 }
}

---

7.2 Detalhar Pagamento de Boleto

GET /quickpay/boleto/payments/{id}

Path Params

Parâmetro	Tipo	Descrição
id	integer	ID do registro de pagamento

Retorna os dados completos do pagamento. Retorna 404 se não pertencer à conta.

---

7.3 Consultar Informações do Boleto Externo

POST /quickpay/boleto/info-barcode

Etapa 1 do fluxo de pagamento. Extrai os dados de um boleto externo a partir do código de barras e registra para pagamento.

Request Body

Campo	Tipo	Obrigatório	Descrição
barcode	string	Sim	Código de barras ou linha digitável do boleto (mín 44 caracteres)

Response (201 Created)

{
  "boleto": {
    "id": 10,
    "beneficiary": "EMPRESA XPTO S.A.",
    "document": "12.345.678/0001-90",
    "value": 250.00,
    "due_date": "2024-12-30",
    "barcode": "00190500954014481606906809350314337370000000250"
  }
}

Response (400) — Já pago anteriormente

{ "message": "Este boleto já foi pago anteriormente em 15/12/2024 10:05:00" }

Regras:

• Se o mesmo código de barras já foi pago por esta conta, a operação é bloqueada imediatamente
• O id retornado em boleto.id é necessário para a etapa de pagamento (7.4)

---

7.4 Pagar Boleto Externo

POST /quickpay/boleto/payment-barcode

Etapa 2 do fluxo de pagamento. Efetua o débito. Exige PIN de segurança.

Request Body

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID retornado pelo endpoint de consulta (7.3)
pin	string	Sim	PIN de segurança da conta
description	string	Não	Descrição do pagamento

Response (200 OK)

{
  "id": 10,
  "barcode": "00190500954014481606...",
  "value": 150.00,
  "status": "completed",
  "paid_at": "2024-12-15T10:05:00Z",
  "txid": "idPagamento123"
}

Response (403) — PIN inválido

{ "message": "PIN inválido." }

Response (400) — Boleto já pago ou em processamento

{ "message": "Este boleto já foi pago ou está em processamento." }

Regras:

• O boleto deve ter sido consultado via endpoint 7.3 antes de chamar este endpoint
• Tentativas de pagar o mesmo boleto duas vezes são bloqueadas automaticamente
• O pagamento aparece no extrato como saída

Status de pagamento:

Status	Descrição
pending	Consultado, aguardando pagamento
processing	Pagamento em andamento
completed	Pagamento confirmado

---

8. Pix Out — PixOutController

8.1 Consultar Chave Pix

POST /quickpay/pix/lookup

Consulta os dados de uma chave Pix sem realizar transferência.

Request Body

Campo	Tipo	Obrigatório	Descrição
key	string	Sim	A chave Pix (máx 255)
type	string	Sim	Tipo da chave: cpf, cnpj, email, telefone ou aleatorio

Validações por tipo:

Tipo	Formato esperado
cpf	11 dígitos numéricos
cnpj	14 dígitos numéricos
email	E-mail válido
telefone	11 dígitos numéricos
aleatorio	32 a 37 caracteres

Response (200 OK)

{
  "status": "success",
  "message": "Chave Pix encontrada",
  "data": {
    "nome": "NOME DO TITULAR",
    "documento": "123***78901",
    "banco": "ITAÚ UNIBANCO",
    "agencia": "0001",
    "conta": "98765-4",
    "tipo_conta": "CORRENTE"
  }
}

Response (404)

{ "status": "error", "message": "A chave Pix pesquisada não existe." }

Response (400) — Formato inválido

{ "status": "error", "message": "Chave Pix para CPF deve ter 11 dígitos numéricos." }

---

8.2 Pix Out por Chave

POST /quickpay/pixout/pix-key

Transferência Pix para uma chave. Operação direta, sem etapa de confirmação.

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor em BRL
key	string	Sim	Chave Pix do beneficiário
document	string	Sim	CPF ou CNPJ do beneficiário
message	string	Não	Mensagem Pix (máx 99)

Response (200 OK)

{
  "id": 502,
  "endtoendid": "E001...",
  "txid": "idPagamentoPix",
  "value": -100.00,
  "balance": 1400.00
}

Regras:

• O saldo deve cobrir o valor da transferência mais a taxa da conta
• Saldo insuficiente retorna 400

---

8.3 Pix Out por Dados Bancários

POST /quickpay/pixout/pix-databank

Transferência Pix informando agência e conta do beneficiário. Operação direta.

Request Body

Campo	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor em BRL (até o limite configurado na conta)
beneficiary_document	string	Sim	CPF ou CNPJ do beneficiário
beneficiary_name	string	Sim	Nome do beneficiário (máx 99)
beneficiary_bank_branch	string	Sim	Agência (máx 99)
beneficiary_bank_code	string	Sim	Código do banco (máx 99)
beneficiary_account	string	Sim	Número da conta (máx 99)
beneficiary_account_type	string	Sim	CORRENTE, PAGAMENTO, SALARIO ou POUPANCA
message	string	Não	Mensagem opcional (máx 99)

Response (200 OK) — mesma estrutura do endpoint 8.2.

Regras:

• O valor máximo por transferência é definido pelo limite configurado na conta
• Saldo insuficiente retorna 400

---

9. Webhooks — Reenvio de Notificação

9.1 Reenviar Notificação de Cobrança

POST /quickpay/webhooks/send-charge/{chargeId}

Força o reenvio de uma notificação de webhook para uma cobrança já paga.

Path Params

Parâmetro	Tipo	Descrição
chargeId	integer	ID da cobrança

Response (200 OK)

{
  "message": "Notificação enviada com sucesso",
  "charge_id": 150,
  "status": "success",
  "http_status": 200,
  "error": null,
  "webhook_url": "https://meusite.com/callback",
  "response": { ... }
}

Response (404) — Cobrança não encontrada ou não está paga

{ "message": "Cobrança não encontrada." }

Response (400) — Sem Pix ou Boleto vinculado

{ "message": "Não há PIX ou Boleto associado a esta cobrança." }

Response (500) — Falha no envio para o webhook

{
  "message": "Erro ao enviar notificação",
  "status": "error",
  "http_status": 500,
  "error": "Connection refused",
  "webhook_url": "https://meusite.com/callback"
}

Regras:

• Funciona apenas para cobranças com status Pago
• Se a cobrança tiver boleto e Pix, o webhook do boleto tem prioridade

---

10. Cobranças

10.1 Relatório de Cobranças

GET /quickpay/charges/reports

Retorna dados agrupados de cobranças por período, úteis para gráficos e dashboards.

WARNING

O path /quickpay/chargess/reports (com dois 's') existe por engano — não use. Use sempre /charges/reports.

Query Params

Parâmetro	Tipo	Obrigatório	Descrição
group_by	string	Sim	days (por dia) ou months (por mês)
date_start	date	Sim	Data inicial (Y-m-d)
date_end	date	Sim	Data final (Y-m-d, deve ser ≥ date_start)

Response (200 OK)

[
  {
    "reference_date": "2024-12-01",
    "payment_method": "BOLETO",
    "total_qtd": 5,
    "total_amount_paid": 1250.00,
    "total_value": 1250.00,
    "total_method_paid": 1250.00,
    "total_method_unpaid": 0.00,
    "status": { "title": "Pago", "description": "" }
  }
]

Regras:

• A data de referência usa a data de pagamento para cobranças pagas e a data de vencimento para as demais
• Os dados são agrupados por período + status + método de pagamento

---

10.2 Exportar Cobranças

GET /quickpay/charges/export

Exporta cobranças como arquivo. Com download=true, o arquivo é retornado diretamente; sem ele, é enviado por e-mail.

Query Params

Parâmetro	Tipo	Descrição
format	string	xlsx, csv ou pdf (padrão: xlsx)
download	boolean	true para download imediato; omitir para receber por e-mail
search	string	Filtro por texto
client_id	integer	Filtro por cliente
created_at_start	date	Data inicial de criação
created_at_end	date	Data final de criação
due_date_start	date	Data inicial de vencimento
due_date_end	date	Data final de vencimento
payment_date_start	date	Data inicial de pagamento
payment_date_end	date	Data final de pagamento
status_id	string	Um ou mais IDs de status separados por vírgula

Response — Download direto (download=true): Arquivo binário com Content-Type adequado

Response (202) — Por e-mail (download omitido)

{
  "success": true,
  "message": "Exportação agendada com sucesso!",
  "data": {
    "message": "Sua exportação foi iniciada. Você receberá um email em breve com o link para download."
  }
}

Regras:

• download=true é síncrono — pode ter timeout para grandes volumes. Prefira a versão assíncrona (por e-mail) em relatórios grandes.

---

10.3 Download de Comprovante de Cobrança

GET /quickpay/charges/{id}/download

Gera e faz download do comprovante PDF de uma cobrança.

Path Params

Parâmetro	Tipo	Descrição
id	string	ID ou código da cobrança

Response (200 OK) — arquivo PDF para download

Content-Type: application/pdf
Content-Disposition: attachment; filename="comprovante_150.pdf"

---

10.4 Notificar Cliente sobre Cobrança

POST /quickpay/charges/{id}/notify

Envia uma notificação ao cliente vinculado à cobrança.

Path Params

Parâmetro	Tipo	Descrição
id	integer	ID da cobrança

Request Body

Campo	Tipo	Obrigatório	Descrição
message	string	Não	Mensagem personalizada (máx 255)

Response (200 OK)

{ "message": "Notificação enviada com sucesso!" }

Response (500) — Falha no envio

{ "message": "Falha ao enviar notificação", "error": "..." }

---

11. Transações e Extrato

11.1 Listar Transações

GET /quickpay/transactions

Retorna o histórico paginado de transações da conta com totalizadores financeiros.

Query Params

Parâmetro	Tipo	Descrição
per_page	integer	Itens por página (padrão: 15)
page	integer	Página atual (padrão: 1)
search	string	Busca por texto
type	integer	Filtro por tipo de transação
type_id	integer	Alias de type
type_ids	array	Múltiplos tipos
created_at_start	date	Data inicial
created_at_end	date	Data final
payment_date_start	date	Alias de created_at_start
payment_date_end	date	Alias de created_at_end

Response (200 OK)

{
  "data": [
    {
      "id": 500,
      "datetime": "2024-12-10T15:05:00Z",
      "txid": "abc123",
      "endtoendid": "E001...",
      "value": 100.50,
      "description": null,
      "type": { "slug": "pix-in", "name": "Pix de Entrada" },
      "payer_name": "REMETENTE",
      "payer_document": "12345678901",
      "payer_bank_name": "NUBANK",
      "receiver_name": "EMPRESA X",
      "receiver_document": "98765432000100"
    }
  ],
  "sumary": {
    "total_transactions": 150,
    "income_value": 5000.00,
    "expenses_value": -2000.00
  },
  "meta": { "current_page": 1, "per_page": 15, "total": 150, "last_page": 10 }
}

NOTE

O campo sumary (sem 'a') é a grafia original da API — mantenha assim nos seus clientes.

Regras:

• Retorna apenas transações confirmadas
• income_value e expenses_value no sumary consideram todas as transações do filtro, não apenas a página atual

---

11.2 Evolução de Saldo por Período

GET /quickpay/transactions/balance-summary

Retorna receitas, despesas e saldo acumulado agrupados por dia ou mês.

Query Params

Parâmetro	Tipo	Obrigatório	Descrição
group_by	string	Sim	days ou months
date_start	date	Sim	Data inicial (Y-m-d)
date_end	date	Sim	Data final (Y-m-d)

Response (200 OK)

{
  "data": [
    {
      "period": "2024-12-01",
      "sum": 850.00,
      "running_balance": 1500.00,
      "income": 1000.00,
      "expenses": -150.00,
      "income_count": 3,
      "expenses_count": 2,
      "transactions_count": 5
    }
  ],
  "resume": {
    "period": "total",
    "sum": 3200.00,
    "running_balance": 1500.00,
    "income": 4000.00,
    "expenses": -800.00,
    "income_count": 15,
    "expenses_count": 6,
    "transactions_count": 21
  }
}

Regras:

• running_balance é acumulado — representa o saldo ao final de cada período
• resume totaliza todos os períodos retornados

---

11.3 Download de Comprovante de Transação

GET /quickpay/transactions/{id}/download

Gera e faz download do comprovante PDF de uma transação.

Path Params

Parâmetro	Tipo	Descrição
id	string	ID da transação

Response (200 OK) — arquivo PDF para download

Content-Type: application/pdf
Content-Disposition: attachment; filename="comprovante_{id}{timestamp}.pdf"

---

11.4 Detalhar Transação

GET /quickpay/transactions/{id}

Path Params

Parâmetro	Tipo	Descrição
id	integer	ID da transação

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 500,
    "datetime": "2024-12-10T15:05:00Z",
    "txid": "abc123",
    "endtoendid": "E001...",
    "description": null,
    "value": 100.50,
    "balance": 1600.50,
    "type": { "slug": "pix-in", "name": "Pix de Entrada" },
    "created_at": "2024-12-10T15:05:00Z"
  }
}

Response (404)

{ "error": "Transação não encontrada." }

---

11.5 Extrato por Período

GET /quickpay/extract

Retorna o extrato agrupado por dia com saldo acumulado.

Query Params

Parâmetro	Tipo	Obrigatório	Descrição
payment_date_start	date	Sim	Data inicial (Y-m-d)
payment_date_end	date	Sim	Data final (Y-m-d)
type	integer	Não	Filtro por tipo de transação
type_ids	array	Não	Múltiplos tipos
search	string	Não	Busca por texto

Response (200 OK)

{
  "data": [
    {
      "date": "2024-12-10",
      "transactions": [...],
      "transactions_count": 3,
      "summary": {
        "day_total": 350.50,
        "balance_end_of_day": 1600.50
      }
    }
  ],
  "sumary": {
    "balance": 1600.50,
    "total_transactions": 8,
    "by_type": [
      { "type_name": "Pix de Entrada", "count": 5, "total": 1000.00 },
      { "type_name": "Pix de Saída",   "count": 3, "total": -649.50 }
    ]
  }
}

Regras:

• O saldo inicial do período é calculado com base em todas as transações anteriores à data inicial
• balance_end_of_day acumula o saldo ao final de cada dia
• sumary.balance representa o saldo histórico total da conta, sem filtro de data
• As transações dentro de cada dia são retornadas em ordem cronológica

---

Tabelas de Referência

Status de Boleto

Código	Label	Descrição
0	Pendente	Aguardando pagamento
1	Pago	Pagamento confirmado
-5	Cancelado	Baixa bancária confirmada
3	Expirado	Vencimento ultrapassado sem pagamento
4	Falhou	Erro no registro junto ao banco
5	Pago com Pix	Liquidado via QR Code Pix (Bolepix)
-1	Deletado	Cancelado ou removido

Status de Saque

Valor	Título	Descrição
aguardando	Aguardando	Aguardando confirmação do PIN
concluido	Pago	Transferência realizada com sucesso
erro	Falha	Erro na transferência
awaiting_payment	Aguardando	Aguardando processamento
processing_payment	Processando	Em fila de processamento
paid	Pago	Liquidado (legado)

Tipos de Transação

Slug	Descrição
pix-in	Recebimento via Pix
pix-out	Transferência Pix enviada
taxa	Taxa sobre operação
taxa-pix-out	Taxa sobre Pix enviado
pagamento-boleto	Pagamento de boleto externo
bolepix	Bolepix (boleto + Pix)

---

Resumo de Problemas Conhecidos

Endpoint	Problema	Use em vez disso
POST /saida-sicred	Configuração bancária fixa, não suporta múltiplas contas	POST /withdraws + POST /withdraws/confirm
POST /pix-out/dataBank	Bug: valor do extrato gerado incorreto	POST /pixout/pix-databank
POST /boleto-saida-sicred	Não implementado — retorna erro 500	—
GET /chargess/reports	Typo no path (dois 's')	GET /charges/reports

---

Última atualização: 2026-05-19