跳到主要内容

代收账单（公用事业/税费）批量支付确认

本文描述与 代收账单批量支付确认（公用事业/税费） 当操作在确认步骤要求 双因素认证 (2FA) 时：请求体必须包含 tfa_info，并与 batch_status: approved 或 batch_status: rejected 一起发送。随后，批次会处于 pending_2fa_approval（待批准）或 pending_2fa_rejection（待拒绝），直到完成 token 校验。

代收账单（公用事业/税费）

该类收费由公用事业公司（水、电、电话、燃气）及政府机构（税费）开具。此类票据不在银行间清算系统（CIP/Núclea）登记，因此返回信息与银行票据不同。

请求​

请求 Endpoint​

ENDPOINT
/bill_payment/account/ACCOUNT_KEY/payment/batch_collection_slip/PAYMENT_BATCH_KEY/confirmation
方法
PATCH

请求 Path Params​

字段类型描述字符数
account_key *uuid4账户唯一标识键。36
payment_batch_key *uuid4批次唯一标识键（创建批次时返回的 batch_payment_key）。36

请求 Body​

请求体：拒绝批次（含 tfa_info）

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

请求体：批准批次（含 tfa_info）

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

Body 参数​

字段类型描述
batch_status *string批次决策。可选值：approved（继续处理流程）或 rejected（取消批次）。见 batch_confirmation_status 枚举。
tfa_infoobject该流程在 batch_status: approved 或 batch_status: rejected 时为必填；请在 tfa_info 对象 中提供审批人及 token 发送渠道。

枚举 batch_confirmation_status​

batch_status 在请求体中的可选值：

值描述
approved批准批次并继续处理流程。
rejected拒绝批次；代收账单将不进入异步处理。

Object tfa_info​

字段类型描述
approver_document_number *string接收 token 的审批人证件号（CPF）。提供 tfa_info 时必填。
contact_type *stringtoken 发送渠道（例如 sms 或 email），遵循业务与账户规则。提供 tfa_info 时必填。

响应​

响应中的 HTTP 状态码和 batch_status 取决于提交的决策，以及该流程在本次调用后是否要求 token 校验。

响应：拒绝决策批次 — 等待 token 校验（2FA）​

STATUS
202

当请求体中的 batch_status 为 rejected 且包含 tfa_info 时，API 返回 202。批次进入 token 校验等待状态，响应体中 batch_status 为 pending_2fa_rejection。token 校验完成后，拒绝决策生效。

Response Body: 批次等待 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"
}

响应：批准决策批次 — 等待 token 校验（2FA）​

STATUS
202

当请求体中的 batch_status 为 approved 且包含 tfa_info 时，API 返回 202。批次进入 token 校验等待状态，响应体中 batch_status 为 pending_2fa_approval。 后续步骤见 代收账单批次 token 校验 以及 重发代收账单批次 token。

Response Body: 批次等待 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"
}

响应 Body Params​

字段类型描述
batch_payment_key *uuid4批量支付唯一标识键。
request_control_key *uuid4客户端请求唯一标识键（批次）。
account_key *uuid4扣款账户键。
total_amount *number批次内所有项目金额之和。
batch_status *string在该调用中，批次会保持在 pending_2fa_approval（待批准）或 pending_2fa_rejection（待拒绝），直到完成 token 校验。校验后最终状态将反映确认步骤提交的决策（approved 或 rejected）。
payment_type *string支付类型；该流程应为 collection_slip。

错误响应​

STATUS
4XX

Response Body

{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
HTTP 代码QI 代码标题描述 (eng)描述 (pt-br)
400BIP000013Bad RequestThe source account is closed.源账户已关闭。
400BIP000050Bad RequestRequester configuration does not exist请求方配置不存在。
400BIP000054Bad RequestTFA info required.需要 TFA 信息.
404BIP000083Not FoundBatch payment not found by batch payment key.未通过批次 key 找到批量支付。
400BIP000084Bad RequestBatch payment status is not pending.批量支付状态不是待处理。