Criação de CCB — Pagamento de Boleto (BILLET

Visão Geral

Neste fluxo, o desembolso da CCB é realizado via liquidação de boleto bancário. O payload carrega os dados do boleto previamente validado no array billets_info, incluindo o código digitável, valores, datas e hashes de validação.

Assim como no fluxo de QR Code PIX, o boleto deve ser validado antes da criação da Application — o campo validation_hash

Etapa 1 — Validação do Boleto

Antes de criar a Application, o boleto deve ser validado para confirmar que o valor e o beneficiário são compatíveis com a operação. O validation_hash retornado deve ser incluído no campo correspondente dentro de billets_info.

Consulte a massa de testes aqui

1. Validar o boleto → curl --location --request POST '{{api_host}}/banking/originator/billets/validate-billets' \
--header 'Authorization: {{originator_access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "billets": [
    {
      "digitable_or_bar_code": "23797898400001500003381260083013525600006330"
    },
    {
      "digitable": "00190000090100159000700117369173390420000098888"
    },
    {
      "bar_code": "00191000000000341080000003373384221022152517"
    }
  ]
}'

Etapa 2 — Criação da Application

Endpoint

POST /banking/originator/applications

Payload Completo

{
  "product": {
    "id": "d4e5252f-f3fc-47a3-8ef9-7a8d9ff4e60f"
  },
  "borrower": {
    "id": "a03f9d67-1afa-48df-b1c5-537be306f26e"
  },
  "funding": {
    "id": "7b8432fb-34e7-4f14-ba6a-a24dc2b29c35"
  },
  "simulation_id": "e5d70282-00be-4ce9-8ec3-a66b88a42f56",
  "payment_method": "BILLET_PAYMENT",
  "billets_info": [
    {
      "digitable": "12190000050000001111442325241141800000000000000",
      "type": 2,
      "amount": 1500,
      "assignor": "BANCO GERADOR S.A.",
      "payer": "PAGADOR AMBIENTE DE HOMOLOGACAO",
      "recipient": "BENEFICIARIO AMBIENTE HOMOLOGACAO",
      "original_amount": 1500,
      "settle_date": "10/03/2026",
      "document_payer": "698.447.801-44",
      "document_recipient": "87.754.347/0001-08",
      "validation_hash": "9fed06ed460c1bf287e442b4a5dc7bcb",
      "discount_amount": 0,
      "fine_amount": 0
    }
  ]
}

billets_info é um array — é possível incluir múltiplos boletos em uma única operação, desde que a soma dos amount seja compatível com o valor da simulação.

Referência de Campos

Campos raiz

Campo	Tipo	Obrigatório	Descrição
`product.id`	uuid	sim	ID do produto configurado
`borrower.id`	uuid	sim	ID do tomador cadastrado
`funding.id`	uuid	sim	ID do fundo/originador
`simulation_id`	uuid	sim	Retornado pelo endpoint `/preview`. Vincula os dados da simulação
`payment_method`	enum	sim	Método de pagamento do desembolso. `BILLET_PAYMENT` para este fluxo
`billets_info`	array	sim	Lista de boletos a serem liquidados no desembolso

Objeto dentro de `billets_info`

Campo	Tipo	Obrigatório	Descrição
`digitable`	string	sim	Código digitável do boleto (linha digitável)
`type`	integer	sim	Tipo do boleto. `1` = convênio · `2` = banco
`amount`	number	sim	Valor a ser pago neste boleto (pode ser diferente do `original_amount` se houver desconto ou multa)
`original_amount`	number	sim	Valor original do boleto sem ajustes
`assignor`	string	sim	Nome do banco/cedente emissor do boleto
`payer`	string	sim	Nome do pagador identificado no boleto
`recipient`	string	sim	Nome do beneficiário/recebedor do boleto
`document_payer`	string	sim	CPF ou CNPJ do pagador (com formatação)
`document_recipient`	string	sim	CPF ou CNPJ do beneficiário (com formatação)
`settle_date`	string	sim	Data de vencimento/liquidação no formato `DD/MM/YYYY`
`validation_hash`	string	sim	Hash retornado pela validação prévia do boleto. Garante integridade dos dados
`discount_amount`	number	não	Valor de desconto aplicado. Enviar `0` se não houver
`fine_amount`	number	não	Valor de multa aplicada. Enviar `0` se não houver

Diferenças em Relação ao Fluxo de QR Code PIX

	Pagamento via Boleto	Pagamento via QR Code PIX
`payment_method`	`BILLET_PAYMENT`	`QRCODE_PIX`
Dados de pagamento	`billets_info`	`beneficiary_account`
Identificador	Código digitável	Chave PIX + EMV
Múltiplos destinos	Sim — array com N boletos	Não — único QR Code por operação
Validação prévia	`validation_hash`	`/validate-pix-emv`

Observações Importantes

validation_hash é obrigatório — deve ser obtido na etapa de validação do boleto. Enviar um hash inválido ou ausente resultará em erro no processamento do desembolso.

Múltiplos boletos — o array billets_info aceita mais de um boleto por operação. A soma dos campos amount de todos os itens deve ser compatível com o valor da simulação.

settle_date — deve ser uma data válida e não vencida no momento do desembolso. Boletos vencidos podem ser recusados dependendo da política do banco emissor.

beneficiary_account não deve ser enviado neste fluxo — é exclusivo para operações QRCODE_PIX e será ignorado ou retornará erro se enviado junto com payment_method: BILLET_PAYMENT.

simulation_id — expira após um período configurado no produto. Sempre crie a Application logo após a simulação para evitar expiração.

Erros Comuns

Situação	Causa provável
Boleto recusado no desembolso	`validation_hash` inválido ou expirado
Valor divergente	Soma dos `amount` em `billets_info` não corresponde ao valor da simulação
Boleto vencido	`settle_date` anterior à data do desembolso
`document_recipient` inválido	CPF/CNPJ do beneficiário com formatação incorreta ou não elegível
`simulation_id` expirado	Tempo entre simulação e criação excedeu o limite configurado no produto

Documento gerado para integração técnica. Em caso de dúvidas, acione o time de suporte via canal dedicado.