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

Este documento descreve a mesma rota de Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) quando a operação exige autenticação de dois fatores (2FA) na etapa de confirmação: o corpo da requisição deve incluir tfa_info junto com batch_status: approved ou batch_status: rejected. Em seguida, o lote pode ficar em pending_2fa_approval (aprovação) ou pending_2fa_rejection (rejeição) até a validação do token.

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 (com tfa_info)

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

Request Body: Aprovação do lote (com tfa_info)

{
  "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	Obrigatório neste fluxo com batch_status: approved ou batch_status: rejected; informe aprovador e canal de envio do token em objeto tfa_info.

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 validação do token após esta chamada.

Resposta: lote rejeitado — pendência de validação do token (2FA)

STATUS

202

Quando batch_status no corpo da requisição é rejected e a requisição inclui tfa_info, a API responde com 202. O lote fica aguardando validação do token; o corpo retorna batch_status como pending_2fa_rejection. Após a validação do token, a decisão de rejeição é aplicada.

Response Body: Lote aguardando validação do token (decisão de rejeição)

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

Resposta: lote aprovado — pendência de validação do token (2FA)

STATUS

202

Quando batch_status no corpo é approved e a requisição inclui tfa_info, a API responde com 202. O lote fica aguardando validação do token; o corpo retorna batch_status como pending_2fa_approval. Os passos seguintes estão em Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo) e Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo).

Response Body: Lote aguardando validação do token

{
  "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_rejection",
  "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	Nesta chamada, o lote permanece em pending_2fa_approval (aprovação) ou pending_2fa_rejection (rejeição) até a validação do token. Após a validação, o status final reflete a decisão enviada na confirmação (approved ou rejected).
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.