Token validation for bank slip payment batch

This endpoint completes the two-factor authentication (2FA) step for a bank slip batch that, after batch confirmation with tfa_info, is in batch_status pending_2fa_approval (approval) or pending_2fa_rejection (rejection). After token validation, the batch proceeds to asynchronous payment processing, and the final status reflects the decision recorded at confirmation (approved or rejected). To request a new token while the batch is in pending_2fa_approval (approval) or pending_2fa_rejection (rejection), use Resend token for bank slip payment batch confirmation.

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/validate_token

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

Authentication via Email and SMS

Request Body: Batch token validation

{
  "token": "329adf"
}

Authentication via Device

To complete device authentication, the request must be sent with an empty payload. Validation is performed internally, with no additional request body information required. This endpoint should only be used after the batch enters pending_2fa_approval (approval) or pending_2fa_rejection (rejection) at batch confirmation with tfa_info.

Request Body: Batch token validation

{

}

Body Params

Field	Type	Description	Characters
token	string	Authentication code sent to the account transaction approver required for TFA via SMS or email	6

Response

Success Response

After successful validation, the API responds with 202 and the batch is processed asynchronously. The final status follows the decision registered in confirmation (approved or rejected).

STATUS

202

Response Body: Batch after token validation (example with approved 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": "approved",
  "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	After token validation, the final status reflects the decision registered during confirmation (approved or rejected). The batch_status cycle follows the batch payment request documentation available for your operation (enumerator batch_payment_status).
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)
403	BIP000010	Forbidden	User is not allowed to do this action	User is not allowed to do this action
404	BIP000011	Not Found	The source account key was not found.	The source account key was not found.
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	BIP000058	Bad Request	Error while validating verification token	Error while validating verification token
400	BIP000059	Bad Request	Number of verification token validation attempts exceeded.	Number of verification token validation attempts exceeded.
400	BIP000060	Bad Request	Verification token expired.	Verification token expired.
400	BIP000061	Bad Request	Verification token validation failed.	Verification token validation failed.
400	BIP000065	Bad Request	Payment verification time window exceeded.	Payment verification time window exceeded.
404	BIP000083	Not Found	Batch payment not found by batch payment key.	Batch payment not found by batch payment key.
400	BIP000085	Bad Request	Batch payment status is not pending approval.	Batch payment status is not pending approval.
400	BIP000086	Bad Request	A token is required for SMS or email validation.	A token is required for SMS or email validation.