Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)

Este endpoint permite confirmar ou rejeitar um lote de pagamento de faturas de recolhimento previamente criado com Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição).

Dependendo da configuração, pode ou não haver autenticação de dois fatores.

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.

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/payment/batch_collection_slip/PAYMENT_BATCH_KEY/confirmation

MÉTODO

PATCH

Request Path Params

Campo	Tipo	Descrição	Caracteres
account_key *	uuid4	Chave única de identificação da conta.	36
payment_batch_key *	uuid4	Chave única de identificação do lote (batch_payment_key retornado na criação do lote).	36

Request Body

Request Body: Rejeição do lote

{
  "batch_status": "rejected"
}

Request Body: Aprovação do lote (sem autenticação de dois fatores)

{
  "batch_status": "approved"
}

Request Body: Aprovação do lote (com autenticação de dois fatores)

{
  "batch_status": "approved",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}

Body Params

Campo	Tipo	Descrição
batch_status *	string	Decisão sobre o lote. Valores: approved (seguir com o processamento) ou rejected (cancelar o lote). Ver enumerador batch_confirmation_status.
tfa_info	object	Quando a autenticação de dois fatores estiver ativa para o fluxo, é obrigatório com batch_status: approved; informe aprovador e canal de envio do token em objeto tfa_info. Caso contrário, omita o campo. Para rejected, tfa_info não se aplica.

Enumerador batch_confirmation_status

Valores aceitos no corpo da requisição para batch_status:

Valor	Descrição
approved	Aprovar o lote e continuar o fluxo de processamento.
rejected	Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento.

Objeto tfa_info

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

O status HTTP e o campo batch_status na resposta dependem da decisão enviada e de o fluxo exigir ou não autenticação de dois fatores.

Resposta: lote rejeitado

STATUS

200

Quando batch_status no corpo da requisição é rejected, a API responde com 200. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento das faturas de recolhimento.

Response Body: Lote rejeitado

{
  "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": "rejected",
  "payment_type": "collection_slip"
}

Resposta: lote aprovado — processamento assíncrono ou pendência de 2FA

STATUS

202

Quando batch_status no corpo é approved, a API responde com 202:

• Sem autenticação de dois fatores: não há etapa de token nesta confirmação; o lote segue para processamento assíncrono das faturas de recolhimento. O corpo retorna batch_status como approved.
• Com autenticação de dois fatores: após aceitar a requisição com tfa_info, o lote fica aguardando validação do token; o corpo retorna batch_status como pending_2fa_approval. A validação do token é feita no endpoint Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo).

Response Body: Lote aprovado para processamento assíncrono

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

Response Body: Lote aprovado, aguardando confirmação 2FA

{
  "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_2fa_approval",
  "payment_type": "collection_slip"
}

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 dos itens do lote.
batch_status *	string	Status do lote após esta chamada (rejected, approved ou pending_2fa_approval). Alinhado ao ciclo de vida em Solicitar pagamento em lote de fatura de recolhimento — batch_payment_status.
payment_type *	string	Tipo do pagamento; para este fluxo, espera-se 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	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000050	Bad Request	Requester configuration does not exist	Configuração do requester não existe.
400	BIP000054	Bad Request	TFA info required.	Informações de TFA necessárias.
404	BIP000083	Not Found	Batch payment not found by batch payment key.	Lote de pagamentos não encontrado pela chave do lote.
400	BIP000084	Bad Request	Batch payment status is not pending.	O status do lote de pagamentos não está pendente.