Bank slip payment batch confirmation

This document describes the same route as Bank slip payment batch confirmation 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.

Bank slip

A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank.

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/payment/batch_bank_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

Value	Description
approved	Approve the batch and continue the processing flow.
rejected	Reject the batch; there is no asynchronous processing of bank 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": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_approval",
  "payment_type": "bank_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 (code delivery, validation, and resend) are documented in Batch bank slip token validation and Resend batch bank 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": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_rejection",
  "payment_type": "bank_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 bank_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.