Skip to content

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étodoRotaO que faz
POST/banking/boleto/payments/decodeConsulta o boleto no banco e prepara o pagamento
POST/banking/boleto/payments/payPaga o boleto consultado (PIN)
GET/banking/boleto/paymentsLista 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" }
CampoRegras
barcodeCó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ódigoQuando
422Código inválido (errors.barcode)
422Boleto já pago por esta conta (Este boleto já foi pago em dd/mm/aaaa hh:mm:ss.) ou com pagamento em processamento
4xxRecusa 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" }
CampoRegras
idObrigatório. data.id do decode
pinObrigatório. PIN da conta, 6 dígitos
descriptionOpcional, até 140 caracteres (padrão: Pagamento {código})

Como funciona:

  1. Confere o PIN, que o boleto está pendente e que o saldo cobre o valor.
  2. Marca o pagamento como processing e grava antes de chamar o banco. Um segundo pedido para o mesmo boleto recebe 422 enquanto isso.
  3. Chama o banco:
    • pago: o pagamento vira completed, com paid_at e txid, e é lançada a transação pagamento-boleto com 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 processing e responde 502. Assim, um novo pedido não paga em duplicidade. Confira o extrato ou o banco antes de qualquer ação.

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ódigoQuando
422PIN inválido ou não configurado (errors.pin)
422Boleto já pago ou em processamento; saldo insuficiente
404id inexistente ou de outra conta
4xxRecusa do banco (pagamento volta para pending)
502Banco não confirmou (pagamento fica em processing)
500Banco 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 antigaRota novaO que muda
POST /quickpay/boleto/info-barcodePOST /banking/boleto/payments/decodeResposta em data (antes em boleto); aceita linha digitável com pontuação
POST /quickpay/boleto/payment-barcodePOST /banking/boleto/payments/payResposta em data com o pagamento (antes, o registro solto); PIN inválido agora é 422 com errors.pin (antes, 403)
GET /quickpay/boleto/paymentsGET /banking/boleto/paymentsEnvelope { 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.