Solicitar Pagamento em Lote de Boleto Bancário

Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição. Para cada item do lote, a plataforma realiza internamente a consulta do boleto para obter dados atualizados, utilizando essas informações para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.

Boleto bancário

É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.

Fluxo após a solicitação

Dependendo do fluxo habilitado para a operação, o lote pode seguir para processamento sem a etapa de confirmação ou permanecer aguardando a confirmação do lote. A autenticação de dois fatores (2FA) pode ou não ser exigida nesta solicitação; quando for exigida aqui, o corpo deve incluir tfa_info conforme o objeto tfa_info abaixo (a confirmação do lote pode ter regras próprias de 2FA, descritas na documentação desse endpoint).

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/payments/batch_bank_slip

MÉTODO

POST

Request Path Params

Campo	Tipo	Descrição	Caracteres
account_key *	uuid4	Chave única de identificação da conta.	36

Request Body: Pagamento em lote de boletos bancários

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5
    }
  ]
}

Request Body: com autenticação de dois fatores na solicitação

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    }
  ]
}

Body Params

Campo	Tipo	Descrição
request_control_key *	uuid4	Chave única de identificação da requisição do cliente (lote).
tfa_info	object	Quando o 2FA for exigido nesta etapa (solicitação do lote), envie aprovador e canal de envio do token no objeto tfa_info. Caso o fluxo não exija 2FA na solicitação, omita o campo.
bank_slip_payments *	array	Lista de pagamentos de boleto bancário. Limite de 1000 itens por requisição.

Cada elemento de bank_slip_payments deve conter:

Campo	Tipo	Descrição
request_control_key *	uuid4	Chave única de identificação da requisição do cliente para aquele item do lote.
barcode	string	Código de barras.
digitable_line	string	Linha digitável.
payment_amount *	number	Valor a ser pago.

Aviso

Para cada item, o payment_amount enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial não for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o payment_amount pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.

Objeto tfa_info

Os campos são os mesmos utilizados na confirmação do lote quando o 2FA se aplica naquela etapa.

Campo	Tipo	Descrição
approver_document_number *	string	Documento (CPF) da pessoa aprovadora que receberá o token. Obrigatório quando tfa_info é enviado.
contact_type *	string	Canal para envio do token (por exemplo sms ou email), conforme regras da operação e cadastro. Obrigatório quando tfa_info é enviado.

Response

Success Response

STATUS

202

Response Body: Lote aceito para processamento

{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending",
  "payment_type": "bank_slip"
}

Response Body: exemplo quando o fluxo não exige confirmação (ilustrativo)

{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}

Processamento do lote

O campo batch_status na resposta indica o estado imediato do lote após esta solicitação (por exemplo, pendente de confirmação, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável — não há um único valor fixo. Quando existir etapa obrigatória de confirmação do lote, ela deve ser realizada nesses casos; quando o fluxo não exigir confirmação, o processamento pode prosseguir sem essa chamada. O 2FA pode integrar esta solicitação (tfa_info), a confirmação ou nenhuma das duas, conforme o fluxo. Os valores possíveis de batch_status estão em batch_payment_status.

Response Body Params

Campo	Tipo	Descrição
batch_payment_key *	uuid4	Chave única de identificação do pagamento em lote.
request_control_key *	uuid4	Chave única de identificação da requisição do cliente (lote).
account_key *	uuid4	Chave da conta debitada.
total_amount *	number	Soma dos valores (payment_amount) dos itens do lote.
batch_status *	enum	Status do lote logo após a solicitação; depende do fluxo (confirmação, 2FA e processamento imediato).
payment_type *	enum	Tipo do pagamento.

Enumeradores batch_payment_status

Enumerador	Descrição
pending	Pendente de processamento
pending_2fa_approval	Pendente de aprovação 2FA
rejected	Rejeitado
approved	Aprovado
processed	Processado

Enumeradores payment_type

Enumerador	Tipo	Descrição
bank_slip	string	Boleto bancário
collection_slip	string	Fatura de recolhimento

Aviso

O enumerador collection_slip não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se payment_type com valor bank_slip.

Error Response

STATUS

4XX

Response Body

{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}

Código HTTP	Código QI	Título	Descrição (eng)	Descrição (pt-br)
403	BIP000010	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BIP000011	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BIP000012	Bad Request	It was not possible to consult the source account at this time. Please try again in a few minutes.	Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400	BIP000024	Bad Request	Request control key already exists.	Chave de controle da requisição já existe.
400	BIP000050	Bad Request	Requester configuration does not exist.	Configuração do requester não existe.
400	BIP000080	Bad Request	Beneficiary bank code of this bank slip is not allowed.	Banco beneficiário desse boleto não é permitido.
400	BIP000081	Bad Request	A list of bank slip payments must be provided.	Uma lista de boletos bancários deve ser fornecida.