Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo)
Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição. Para cada item do lote, a plataforma realiza internamente a consulta da fatura para obter dados atualizados, utilizando essas informações para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
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
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 faturas de recolhimento
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
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"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
}
]
}
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. |
collection_slip_payments * | array | Lista de pagamentos de fatura de recolhimento. Limite de 1000 itens por requisição. |
Cada elemento de collection_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. |
Para cada item, o payment_amount enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao total_amount e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
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
Response Body: Lote aceito para processamento
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending",
"payment_type": "collection_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": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
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 |
O enumerador bank_slip não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se payment_type com valor collection_slip.
Error Response
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) |
|---|---|---|---|---|
| 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 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |