Collection slip (utility/tax) payment batch confirmation

This document describes the same route as Collection slip payment batch confirmation (utility/tax) when the operation requires two-factor authentication (2FA) at the confirmation step: the request body must include tfa_info together with batch_status: approved or batch_status: rejected. Then, the batch may remain in pending_2fa_approval (approval) or pending_2fa_rejection (rejection) until token validation.

Collection slip (utility/tax bill)

This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip.

Request

Request Endpoint

ENDPOINT

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

METHOD

PATCH

Request Path Params

Field	Type	Description	Characters
account_key *	uuid4	Unique account identifier.	36
payment_batch_key *	uuid4	Unique batch identifier (batch_payment_key returned at batch creation).	36

Request Body

Request Body: Batch rejection (with tfa_info)

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

Request Body: Batch approval (with tfa_info)

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

Body Params

Field	Type	Description
batch_status *	string	Batch decision. Values: approved (continue processing) or rejected (cancel the batch). See batch_confirmation_status enumerator.
tfa_info	object	Required in this flow with batch_status: approved or batch_status: rejected; provide approver information and token delivery channel in tfa_info object.

Enumerator batch_confirmation_status

Accepted values in the request body for batch_status:

Value	Description
approved	Approve the batch and continue the processing flow.
rejected	Reject the batch; there is no asynchronous processing of collection slips.

Object tfa_info

Field	Type	Description
approver_document_number *	string	Approver person's document number (CPF) that will receive the token. Required when tfa_info is provided.
contact_type *	string	Channel used to send the token (for example, sms or email), according to operation and registration rules. Required when tfa_info is provided.

Response

The HTTP status and the batch_status field in the response depend on the submitted decision and whether the flow requires token validation after this call.

Response: rejected batch — pending token validation (2FA)

STATUS

202

When batch_status in the request body is rejected and the request includes tfa_info, the API responds with 202. The batch waits for token validation, and the body returns batch_status as pending_2fa_rejection. After token validation, the rejection decision is applied.

Response Body: Batch waiting for token validation (rejection decision)

{
  "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: approved batch — pending token validation (2FA)

STATUS

202

When batch_status in the body is approved and the request includes tfa_info, the API responds with 202. The batch waits for token validation, and the body returns batch_status as pending_2fa_approval. Next steps are documented in Batch collection slip token validation and Resend batch collection slip token.

Response Body: Batch waiting for token validation

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

Field	Type	Description
batch_payment_key *	uuid4	Unique batch payment identifier.
request_control_key *	uuid4	Unique client request identifier (batch).
account_key *	uuid4	Debited account key.
total_amount *	number	Sum of the amounts of all batch items.
batch_status *	string	In this call, the batch remains in pending_2fa_approval (approval) or pending_2fa_rejection (rejection) until token validation. After validation, the final status reflects the decision sent in confirmation (approved or rejected).
payment_type *	string	Payment type; for this flow, expected value is collection_slip.

Error Response

STATUS

4XX

Response Body

{
    "title": "Title",
    "description": "Description in english",
    "translation": "Description em português",
    "code": "Code"
}

HTTP code	QI code	Title	Description (eng)	Description (pt-br)
400	BIP000013	Bad Request	The source account is closed.	The source account is closed.
400	BIP000050	Bad Request	Requester configuration does not exist	Requester configuration does not exist.
400	BIP000054	Bad Request	TFA info required.	TFA info required.
404	BIP000083	Not Found	Batch payment not found by batch payment key.	Batch payment not found by batch payment key.
400	BIP000084	Bad Request	Batch payment status is not pending.	Batch payment status is not pending.