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.

Fatura de recolhimento

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.

Fluxo após a solicitação

Após a solicitação, o lote pode permanecer aguardando a confirmação do lote, conforme as regras da operação.

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/payments/batch_collection_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 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
    }
  ]
}

Body Params

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

Aviso

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.

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": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending",
  "payment_type": "collection_slip"
}

Response Body: exemplo ilustrativo (batch_status aprovado)

{
  "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"
}

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 ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de confirmação do lote, utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. 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 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 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

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)
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.