Aparência
Banking — Pagamento de boletos
Paga boletos de terceiros (contas, fornecedores, tributos com código de barras) usando o saldo da conta. O fluxo tem duas etapas, como o Pix copia e cola: consultar o boleto e depois pagar com o PIN.
Disponível para contas dos bancos cujo driver implementa a consulta e o pagamento: hoje só o Teste. Na Fidúcia (ainda não implementado) as rotas respondem 422 Pagamento de boleto não está disponível para o banco desta conta.
Autenticação e headers: Banking — visão geral.
| Método | Rota | O que faz |
|---|---|---|
POST | /banking/boleto/payments/decode | Consulta o boleto no banco e prepara o pagamento |
POST | /banking/boleto/payments/pay | Paga o boleto consultado (PIN) |
GET | /banking/boleto/payments | Lista os pagamentos de boleto da conta |
GET | /banking/boleto/payments/{id} | Detalhe de um pagamento |
Não há taxa no pagamento de boleto.
POST /banking/boleto/payments/decode
json
{ "barcode": "34191.79001 01043.510047 91020.150008 1 96610000010000" }| Campo | Regras |
|---|---|
barcode | Código de barras (44 dígitos) ou linha digitável (47 ou 48 dígitos). Pontos, espaços e outros separadores são removidos antes da validação |
Consulta o boleto no banco e grava um pagamento pendente para a conta, reaproveitando o registro se o mesmo código já foi consultado. O id devolvido é o que vai no pay.
Response 200 (trecho; os campos vêm do banco e variam):
json
{
"code": 200,
"success": true,
"data": {
"id": 1,
"codigoBarras": "34191790010104351004791020150008196610000010000",
"valor": 100,
"valorAtual": 100,
"dataVencimento": "2026-10-08 00:00:00",
"nomeBeneficiario": "...",
"codigoBanco": "...",
"nomeBanco": "...",
"vencido": false,
"pagavel": true
},
"message": "Boleto consultado com sucesso."
}| Código | Quando |
|---|---|
422 | Código inválido (errors.barcode) |
422 | Boleto já pago por esta conta (Este boleto já foi pago em dd/mm/aaaa hh:mm:ss.) ou com pagamento em processamento |
4xx | Recusa do banco na consulta (mensagem do banco) |
POST /banking/boleto/payments/pay
Exige o header
Idempotency-Key(sem ele,428), que evita pagar o mesmo boleto duas vezes. Ver Idempotência.
json
{ "id": 1, "pin": "123456", "description": "Conta de luz" }| Campo | Regras |
|---|---|
id | Obrigatório. data.id do decode |
pin | Obrigatório. PIN da conta, 6 dígitos |
description | Opcional, até 140 caracteres (padrão: Pagamento {código}) |
Como funciona:
- Confere o PIN, que o boleto está pendente e que o saldo cobre o valor.
- Marca o pagamento como
processinge grava antes de chamar o banco. Um segundo pedido para o mesmo boleto recebe422enquanto isso. - Chama o banco:
- pago: o pagamento vira
completed, compaid_atetxid, e é lançada a transaçãopagamento-boletocom o valor negativo; - recusa do banco (4xx): volta para
pending, a mensagem do banco é devolvida com o mesmo status e nada é debitado; - sem confirmação (timeout, erro 5xx ou desconhecido): fica em
processinge responde502. Assim, um novo pedido não paga em duplicidade. Confira o extrato ou o banco antes de qualquer ação.
- pago: o pagamento vira
Response 201:
json
{
"code": 201,
"success": true,
"data": {
"id": 1,
"status": "completed",
"txid": "822681",
"value": 100,
"barcode": "34191790010104351004791020150008196610000010000",
"due_date": "2026-10-08T06:00:00.000000Z",
"json": { "...": "consulta + retorno do banco", "autenticacao": "ZBDV99QYFG" },
"paid_at": "2026-10-03T03:54:31.000000Z",
"created_at": "2026-10-03T03:54:31.000000Z",
"updated_at": "2026-10-03T03:54:31.000000Z"
},
"message": "Boleto pago com sucesso."
}| Código | Quando |
|---|---|
422 | PIN inválido ou não configurado (errors.pin) |
422 | Boleto já pago ou em processamento; saldo insuficiente |
404 | id inexistente ou de outra conta |
4xx | Recusa do banco (pagamento volta para pending) |
502 | Banco não confirmou (pagamento fica em processing) |
500 | Banco confirmou, mas o registro local falhou (fica em processing; não tente de novo, contate o suporte) |
GET /banking/boleto/payments
Lista paginada, mais recentes primeiro. Query: status (pending, processing, completed), per_page (padrão 15), page.
json
{
"data": [
{ "id": 1, "status": "completed", "txid": "822681", "value": 100, "barcode": "3419...", "due_date": "...", "json": { "...": "..." }, "paid_at": "...", "created_at": "...", "updated_at": "..." }
],
"meta": { "total": 1, "page": 1, "limit": 15, "total_pages": 1, "has_next_page": false, "has_prev_page": false }
}GET /banking/boleto/payments/{id}
json
{ "code": 200, "success": true, "data": { "id": 1, "status": "completed", "txid": "822681", "...": "..." } }Pagamento de outra conta ou inexistente: 404.
Migração das rotas antigas (breaking change, 03/10/2026)
As rotas antigas foram removidas e respondem 404:
| Rota antiga | Rota nova | O que muda |
|---|---|---|
POST /quickpay/boleto/info-barcode | POST /banking/boleto/payments/decode | Resposta em data (antes em boleto); aceita linha digitável com pontuação |
POST /quickpay/boleto/payment-barcode | POST /banking/boleto/payments/pay | Resposta em data com o pagamento (antes, o registro solto); PIN inválido agora é 422 com errors.pin (antes, 403) |
GET /quickpay/boleto/payments | GET /banking/boleto/payments | Envelope { data, meta } do padrão da API (antes, { data, links, meta } do Laravel) |
GET /quickpay/boleto/payments/{id} | GET /banking/boleto/payments/{id} | Envelope { code, success, data } |
Correções incluídas:
- O bloqueio de pagamento duplo não funcionava: o status era comparado com o enum, e não com o valor gravado.
- Não havia checagem de saldo.
- A chamada ao banco acontecia dentro da transação local. Se o registro falhasse depois de o banco pagar, o boleto voltava para "pendente" e podia ser pago de novo.
- Consultar de novo um boleto em processamento o voltava para "pendente".
- Erros de regra (já pago, banco sem suporte) saíam como
500.