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.

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

Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo batch_status reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em batch_payment_status.

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
    }
  ]
}

Body Params

Campo	Tipo	Descrição
request_control_key *	uuid4	Chave única de identificação da requisição do cliente (lote).
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.

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 ilustrativo com batch_status aprovado

{
  "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 processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. 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 processamento imediato e das regras da operação.
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.