Aparência
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,emailedocumentjuntos, o cliente é criado ou atualizado pelo documento e vinculado à cobrança. Sem os três, nenhum cliente é criado, e o que vier dename/email/documentfica só no Pix. client_idtambém é aceito.amountrespeita o mínimomin_pix_inda 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"
}| Campo | Obrigatório | Regras / efeito |
|---|---|---|
amount ou value | Sim | Limites da conta: min_boleto_in / max_boleto_in (BOLEPIX: menor mínimo entre Pix e boleto) |
payment_method | Sim | PIX, BOLETO ou BOLEPIX |
due_date | Sim (exceto PIX) | Data ≥ hoje. É o vencimento do boleto |
client_id ou name + email + document | Sim (exceto PIX) | Cliente criado/atualizado pelo documento |
rate + type_rate | Não | Juros enviados ao banco (ABSOLUTE/PERCENTAGE) |
amount_rate | Não | Juros gravados na cobrança (charges.rate) |
discount + days_discount (+ type_discount) | Não | Desconto enviado ao banco (padrão ABSOLUTE) |
late_fee (+ late_fee_type) | Não | Novo. Multa enviada ao banco e gravada em boletos.late_fee (tipo padrão PERCENTAGE) |
informative | Não | Novo. Lista de mensagens informativas do boleto, repassada ao banco |
description, details, instructions, webhook | Não | Como 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).informativeelate_feesó 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=PIXFiltros: 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.
- Boleto pendente: primeiro pede a baixa no banco (
baixarBoleto, com otxiddo boleto, que é o nosso número). Se o banco recusar, responde422com o motivo e nada é alterado. - Com a baixa aceita, o boleto fica
CANCELLED(-5) e a resposta do banco é registrada emboletos.json.deleted_history. - Pix pendente vira
DELETED(-2). - 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ódigo | Quando |
|---|---|
404 | Cobrança de outra conta, inexistente ou excluída (DELETED) |
422 | Cobrança não pendente (paga, já cancelada etc.): Só cobranças pendentes podem ser canceladas. |
422 | Banco 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ódigo | Quando |
|---|---|
404 | Cobrança inexistente, de outra conta ou não paga |
400 | Cobranç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:
- Boleto pendente (
status 0): pedido de baixa no banco (baixarBoleto). Se o banco aceita, o boleto ficaCANCELLED(-5). Se o banco recusa, o boleto ficaDELETED(-1). A tentativa é sempre registrada emboletos.json.deleted_history, e a falha no banco não impede o cancelamento. - Pix pendente (
status 0) viraDELETED(-2). - A cobrança vira
DELETEDe 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/charges | POST /billing/charges com "payment_method": "PIX" |
GET /banking/pix/charges | GET /billing/charges?payment_method=PIX |
GET /banking/pix/charges/{txid} | GET /billing/charges/{id} |
POST /quickpay/boletos · POST /quickpay/boleto/create | POST /billing/charges com BOLETO ou BOLEPIX |
GET /quickpay/boletos · GET /quickpay/boleto/list | GET /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/cancel | DELETE /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
idda cobrança, não otxid. Otxidcontinua emdata.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_dateviroudue_date.hasPix: trueviroupayment_method: "BOLEPIX".- Para boleto,
emailpassa a ser obrigatório (regra de/billing/charges). - O PDF é baixado direto (binário), não mais uma URL de
/storage. hasPDF,messagese o cancelamento em lote (txids[]) não existem em/billing/charges.- Boletos emitidos pelas rotas antigas (
/quickpay/boleto(s)) criaram a cobrança semstatus_id. O filtro global de cobranças (ChargeScope,status_id != DELETED) descartastatus_idnulo, então essas cobranças não aparecem em/billing/chargese 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.