Trabalhando com boletos

Este documento apresenta as especificações dos endpoints para o processamento e pagamento de boletos.

1. Pagamento ou Simulação de Boleto

A API permite o pagamento de boletos de duas formas independentes: utilizando saldo em moeda fiduciária (Reais - FIAT) ou utilizando saldo em Criptomoedas (CRYPTO). O endpoint é unificado e seu comportamento adapta-se aos parâmetros fornecidos.

Endpoint: POST /boletos/pay-boleto

Autenticação Obrigatória: Sim (Header Authorization)

1.1 Parâmetros do Corpo da Requisição (JSON)

Campo	Tipo	Obrigatoriedade	Descrição
`digitableLine`	`string`	Sim	A linha digitável do boleto a ser pago.
`paymentMethod`	`string`	Sim	O método de pagamento. Aceita apenas os valores: `FIAT` ou `CRYPTO`.
`isSimulation`	`boolean`	Sim	Se `true`, a transação não é executada. A API apenas valida os dados e retorna um demonstrativo detalhado de taxas, cotação atual e valores líquidos em R$. É recomendado exibir este retorno ao usuário final antes de processar o pagamento definitivo.
`cryptoToken`	`string`	Condicional	Obrigatório exclusivamente se `paymentMethod` for `CRYPTO`. O símbolo do criptoativo. Veja a tabela de moedas suportadas.
`network`	`string`	Condicional	Obrigatório exclusivamente se `paymentMethod` for `CRYPTO`. A rede blockchain correspondente ao ativo. Veja a tabela de moedas suportadas.

1.1.1 Criptomoedas e Redes Suportadas

Para pagamentos via CRYPTO, as seguintes combinações são aceitas de forma integral:

BTC (Bitcoin): Rede Bitcoin.
USDT (Tether): Redes Ethereum (ERC20), Tron (TRC20) e Polygon.
USDC (USD Coin): Redes Ethereum (ERC20), Polygon, Base, Optimism e Solana.

Exemplo de Requisição: Pagamento com Moeda Fiduciária (FIAT)

{
  "digitableLine": "07797777051177160607318241876111313700000002000",
  "paymentMethod": "FIAT",
  "isSimulation": false
}

Exemplo de Requisição: Pagamento com Criptomoedas (CRYPTO)

A equivalência em Reais (BRL) necessária para a quitação do boleto será automaticamente calculada com base na cotação do momento.

{
  "digitableLine": "07797777051177160607318241876111313700000002000",
  "paymentMethod": "CRYPTO",
  "cryptoToken": "USDC",
  "network": "Polygon",
  "isSimulation": true
}

1.2 Detalhamento das Respostas

Resposta: Cotação e Simulação (`isSimulation: true`)

A resposta indicará a viabilidade da transação, bem como os custos e detalhes finais do ativo debitado no cenário CRYPTO.

{
  "isSimulation": true,
  "canPay": true, 
  "reason": null,
  "paymentMethod": "CRYPTO",
  "boleto": {
    "assignor": "Empresa Recebedora Ltda.",
    "dueDate": "2026-05-10",
    "baseAmount": 150.50,
    "totalFeeAmount": 1.50,
    "netAmount": 152.00
  },
  "cryptoDetails": { 
    "token": "USDC",
    "network": "Polygon",
    "currentPrice": 4.95,
    "cryptoAmount": 30.7070,
    "availableBalance": 500.00,
    "totalFees": 1.50,
    "netAmountBrl": 152.00
  }
}

Resposta: Pagamento efetuado com Sucesso (`isSimulation: false`)

A requisição foi aceita e o pagamento enviado para finalização bancária.

{
  "success": true,
  "message": "Operação de pagamento de boleto criada com sucesso",
  "boletoId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "boletoCriptoOrderId": "a123-b456-c789",
  "transactionId": "t987-u654-v321"
}

2. Consulta de Status do Boleto

Como a retaguarda e a compensação do sistema bancário ocorrem de forma assíncrona, a sua aplicação deve implementar um modelo de polling (consultas periódicas) para garantir o acompanhamento da compensação final do boleto.

Endpoint: GET /boletos/{identifier}

Autenticação Obrigatória: Sim (Header Authorization)

2.1 Parâmetros

Param (Path)	Tipo	Descrição
`identifier`	`string`	O identificador do boleto fornecido pela API. Para máxima compatibilidade, o sistema suporta o ID referenciado (`uuid`), além da própria Linha Digitável ou do Código de Barras.

2.2 Exemplo de Resposta de Consulta

{
  "id": "e30f1d06-4b13-4ae3-94c6-30238e83b150",
  "providerIdReference": "ABC-12345",
  "status": "PAID",
  "transactionStatus": "COMPLETED",
  "executedAt": "2026-04-17T14:30:00Z",
  "barcode": "07797777051177160607318241876111313700000002000",
  "typeableLine": "07797777051177160607318241876111313700000002000",
  "providerPayload": { }
}

Estados Possíveis do Boleto (status):

PROCESSING: O pagamento foi registrado e está na fila bancária.
PAID: Pagamento finalizado e garantido com sucesso.
FAILED / REJECTED: O pagamento retornou uma desaprovação da câmera de conciliação.

Obtendo transações de criptomoedas por ID

Executando SWAP