Skip to content

Cobranças Pix e boleto (/billing/charges) ​

Desde 2 de outubro de 2026, toda cobrança por Pix, boleto ou boleto + Pix (BOLEPIX) é emitida, consultada, baixada em PDF e cancelada só por /billing/charges. As rotas avulsas /banking/pix/charges e /quickpay/boleto(s) foram removidas e respondem 404 (ver migração).

A emissão no banco (Pix dinâmico e boleto) e a baixa ficam num único serviço, App\Services\ChargePaymentService. O mesmo serviço é usado pelas cobranças avulsas e pela troca de valor de uma cobrança Pix (PUT).

Headers:

Authorization: Bearer {token}
Content-Type: application/json
account: {account_id}

POST /billing/charges ​

Aceita o header opcional Idempotency-Key, que evita executar a mesma operação duas vezes. Ver Idempotência.

Pix (receber um valor, sem cliente) ​

Para Pix, cliente e vencimento são opcionais. É o fluxo "Receber via Pix" do portal.

json
{ "amount": 25.00, "payment_method": "PIX" }
  • Com name, email e document juntos, o cliente é criado ou atualizado pelo documento e vinculado à cobrança. Sem os três, nenhum cliente é criado, e o que vier de name/email/document fica só no Pix.
  • client_id também é aceito.
  • amount respeita o mínimo min_pix_in da conta.

Boleto e BOLEPIX ​

json
{
  "amount": 150.75,
  "payment_method": "BOLEPIX",
  "due_date": "2026-10-10",
  "name": "Cliente Boleto",
  "email": "cliente@exemplo.com",
  "document": "52998224725",
  "late_fee": 2,
  "late_fee_type": "PERCENTAGE",
  "rate": 1,
  "amount_rate": 1,
  "type_rate": "PERCENTAGE",
  "discount": 5,
  "days_discount": 2,
  "type_discount": "ABSOLUTE",
  "informative": ["Não receber após o vencimento"],
  "webhook": "https://meusite.com/webhook"
}
CampoObrigatórioRegras / efeito
amount ou valueSimLimites da conta: min_boleto_in / max_boleto_in (BOLEPIX: menor mínimo entre Pix e boleto)
payment_methodSimPIX, BOLETO ou BOLEPIX
due_dateSim (exceto PIX)Data ≥ hoje. É o vencimento do boleto
client_id ou name + email + documentSim (exceto PIX)Cliente criado/atualizado pelo documento
rate + type_rateNãoJuros enviados ao banco (ABSOLUTE/PERCENTAGE)
amount_rateNãoJuros gravados na cobrança (charges.rate)
discount + days_discount (+ type_discount)NãoDesconto enviado ao banco (padrão ABSOLUTE)
late_fee (+ late_fee_type)NãoNovo. Multa enviada ao banco e gravada em boletos.late_fee (tipo padrão PERCENTAGE)
informativeNãoNovo. Lista de mensagens informativas do boleto, repassada ao banco
description, details, instructions, webhookNãoComo antes
  • BOLEPIX emite um boleto e um Pix dinâmico separados, com o mesmo valor; o boleto aponta para o Pix (boletos.pix_id).
  • rate × amount_rate: comportamento de antes, mantido para não mudar cobranças de quem já integra. Para os juros irem ao banco e ficarem na cobrança, envie os dois (o portal faz isso).
  • informative e late_fee só vão ao banco quando preenchidos. Assim, bancos cujo driver não aceita esses parâmetros continuam funcionando.

Response 201 (ChargeResource, trecho):

json
{
  "data": {
    "id": 2,
    "value": 150.75,
    "payment_method": "BOLEPIX",
    "due_date": "2026-10-10T03:00:00.000000Z",
    "client": { "client_id": 1, "name": "Cliente Boleto", "...": "..." },
    "status": { "id": 1, "title": "pending" },
    "pix": {
      "id": 2,
      "txid": "5f8cc3b5-4fe0-4814-b9c0-cd2c0becc97c",
      "qrcode": "00020126440014br.gov.bcb.pix...",
      "amount": 150.75,
      "status": 0
    },
    "boleto": {
      "boleto_id": 1,
      "txid": "NS97220531",
      "barcode": "3150412345...",
      "digitable_line": "25042 12345.67890 ...",
      "late_fee": 2,
      "our_number": "...",
      "your_number": "...",
      "status": 0,
      "amount": 150.75
    }
  }
}

Para Pix, client, due_date e boleto vêm null. pix.qrcode é o copia e cola. O portal monta a imagem do QR Code a partir dele.

Correção nesta versão: boleto.digitable_line vinha sempre null (o resource lia um atributo inexistente). Agora traz a linha digitável. Também passaram a vir late_fee, our_number e your_number.


GET /billing/charges ​

Mesma listagem das cobranças. Para ver só Pix ou só boletos, use payment_method, aceita lista separada por vírgula:

GET /billing/charges?payment_method=BOLETO,BOLEPIX&search=cliente&page=1&per_page=15
GET /billing/charges?payment_method=PIX

Filtros: search, status_id, client_id, payment_method, created_at_start/end, due_date_start/end, payment_date_start/end, order_by, order_dir, per_page, page. Cobranças canceladas (DELETED) não aparecem.

GET /billing/charges/{id} ​

Detalhe de uma cobrança da conta, com pix e boleto. Outra conta ou cancelada: 404.

GET /billing/charges/{id}/download-pdf ​

PDF da cobrança (application/pdf, anexo fatura_{id}.pdf), gerado na hora, com o boleto e o QR Code Pix quando houver. Substitui o antigo POST /quickpay/boletos/{txid}/pdf.

POST /billing/charges/{id}/cancel ​

Cancela uma cobrança pendente e a mantém visível, com status canceled ("Cancelado"). Diferente do DELETE, a cobrança continua nas listagens e no detalhe.

  1. Boleto pendente: primeiro pede a baixa no banco (baixarBoleto, com o txid do boleto, que é o nosso número). Se o banco recusar, responde 422 com o motivo e nada é alterado.
  2. Com a baixa aceita, o boleto fica CANCELLED (-5) e a resposta do banco é registrada em boletos.json.deleted_history.
  3. Pix pendente vira DELETED (-2).
  4. A cobrança passa para o status canceled.

Bancos cujo driver não tem baixa de boleto (hoje Fidúcia e Teste) cancelam só no sistema. O boleto fica CANCELLED com o registro "Banco da conta não suporta baixa de boleto; cancelado só no sistema.", e pode continuar pagável no banco.

Response 200: a cobrança (ChargeResource), com status.title: "canceled".

json
{ "code": 200, "success": true, "data": { "id": 2, "status": { "title": "canceled" }, "...": "..." }, "message": "Cobrança cancelada com sucesso!" }
CódigoQuando
404Cobrança de outra conta, inexistente ou excluída (DELETED)
422Cobrança não pendente (paga, já cancelada etc.): Só cobranças pendentes podem ser canceladas.
422Banco recusou a baixa: O banco recusou a baixa do boleto: ...

POST /billing/charges/{id}/webhook ​

Reenvia ao webhook do cliente a notificação de uma cobrança paga (status paid) da conta ativa. Usa a URL e o txid do boleto ou, se a cobrança não tem boleto, do Pix. Cada tentativa fica registrada em webhook_notifications (consulta em GET /access/webhook-notifications).

Substitui POST /quickpay/webhooks/send-charge/{chargeId}, removido em 03/10/2026 (respondia mesmo para cobranças de outra conta e dava erro 500 em cobrança só Pix; ambos corrigidos).

Response 200 (ou 500 se o webhook do cliente falhar):

json
{
  "message": "Notificação enviada com sucesso",
  "charge_id": "12",
  "status": "success",
  "http_status": 200,
  "error": null,
  "webhook_url": "https://cliente.example.com/hook",
  "webhook_notification_id": 34,
  "response": { "ok": true }
}
CódigoQuando
404Cobrança inexistente, de outra conta ou não paga
400Cobrança sem Pix nem boleto

DELETE /billing/charges/{id} ​

Cancela a cobrança. Novo: agora também cancela os meios de pagamento no banco, numa transação:

  1. Boleto pendente (status 0): pedido de baixa no banco (baixarBoleto). Se o banco aceita, o boleto fica CANCELLED (-5). Se o banco recusa, o boleto fica DELETED (-1). A tentativa é sempre registrada em boletos.json.deleted_history, e a falha no banco não impede o cancelamento.
  2. Pix pendente (status 0) vira DELETED (-2).
  3. A cobrança vira DELETED e some das listagens.

Boleto ou Pix já pagos não são alterados. Resposta igual à de antes:

json
{ "code": 200, "success": true, "data": { "id": 2, "status_id": 4, "...": "..." }, "message": "Cobrança apagado com sucesso!" }

Migração das rotas removidas (breaking change) ​

Rota removida (agora 404)Use
POST /banking/pix/chargesPOST /billing/charges com "payment_method": "PIX"
GET /banking/pix/chargesGET /billing/charges?payment_method=PIX
GET /banking/pix/charges/{txid}GET /billing/charges/{id}
POST /quickpay/boletos · POST /quickpay/boleto/createPOST /billing/charges com BOLETO ou BOLEPIX
GET /quickpay/boletos · GET /quickpay/boleto/listGET /billing/charges?payment_method=BOLETO,BOLEPIX
GET /quickpay/boletos/{txid} · GET /quickpay/boleto/{txid}GET /billing/charges/{id}
POST /quickpay/boletos/{txid}/pdf · POST /quickpay/boleto/pdf/{txid}GET /billing/charges/{id}/download-pdf
POST /quickpay/boletos/cancel · POST /quickpay/boleto/cancelDELETE /billing/charges/{id} (uma por chamada)
DELETE /quickpay/boletos/{txid} · DELETE /quickpay/boleto/{txid}DELETE /billing/charges/{id}

Mudanças de contrato para quem migra:

  • A chave passa a ser o id da cobrança, não o txid. O txid continua em data.pix.txid / data.boleto.txid.
  • A resposta é a da cobrança (data.pix, data.boleto), não mais { pix: {...} } nem o objeto do boleto.
  • expiration_date virou due_date. hasPix: true virou payment_method: "BOLEPIX".
  • Para boleto, email passa a ser obrigatório (regra de /billing/charges).
  • O PDF é baixado direto (binário), não mais uma URL de /storage.
  • hasPDF, messages e o cancelamento em lote (txids[]) não existem em /billing/charges.
  • Boletos emitidos pelas rotas antigas (/quickpay/boleto(s)) criaram a cobrança sem status_id. O filtro global de cobranças (ChargeScope, status_id != DELETED) descarta status_id nulo, então essas cobranças não aparecem em /billing/charges e não podem ser canceladas por ela. Elas já não apareciam antes. Torná-las visíveis exige um ajuste de dados, ainda não feito e pendente de decisão.

Continuam iguais: GET /banking/pix/static-qrcode (QR estático da chave da conta, sem valor). O pagamento de boletos de terceiros foi depois para /banking/boleto/payments (03/10/2026): veja Pagamento de boletos.

Correção de efeito colateral: GET /quickpay/boleto/payments era capturado pela rota removida GET /quickpay/boleto/{txid} (declarada antes) e nunca chegava em BoletoPaymentController@index. Agora chega.