请求双因素认证收款单付款

此端点用于通过双因素认证请求收款单付款。请求应在查询之后进行，使用返回的信息以确保流程正常运行，避免过程中出现失败。

收款单

此类收费由服务特许经营商（水、电、电话和燃气账单）及政府机构（税款）发行。它们不在银行间支付清算所（CIP/Núclea）登记，因此返回的信息与银行划账单不同。

Request

Request Endpoint

ENDPOINT

/account/ACCOUNT_KEY/payment/collection_slip

MÉTODO

POST

Request Path Params

字段	类型	描述	字符数
`account_key` *	uuid4	账户的唯一标识键。	36

通过邮件和短信认证

Request Body: 通过可输入行使用短信或邮件TFA请求收款单

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}

Request Body: 通过条形码使用短信或邮件TFA请求收款单

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}

通过设备认证

除了现有的短信和邮件认证方式外，还可以使用预先注册的设备对交易进行认证。此时，session_id 需从 Device Scan 获取并在 tfa_info 中发送。

Request Body: 通过可输入行使用设备TFA请求收款单

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}

Request Body: 通过条形码使用设备TFA请求收款单

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}

Body Params

字段	类型	描述
`request_control_key` *	uuid4	客户请求的唯一标识键。
`barcode`	string	条形码。
`digitable_line`	string	可输入行。
`payment_amount` *	number	待付金额。
`tfa_info` *	object	包含账户审批人文件及联系方式的对象。

注意

payment_amount 必须始终等于查询银行划账单时返回的 total_amount。

Objeto tfa_info

字段	类型	描述
`approver_document_number`*	string	账户审批人的文件编号（CPF/CNPJ）。
`session_id`	string	设备会话的唯一标识键，UUID v4 格式（设备TFA时为必填项）。
`contact_type`*	enumerator	认证令牌的验证方式

枚举值	描述
sms	发送至手机的短信
email	发送至电子邮件
device	通过设备令牌验证

Response

Success Response

STATUS

201

Response Body: 付款待双因素批准

{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "pending_2fa_approval"
}

Response Body Params

字段	类型	描述
`payment_key` *	uuid4	付款的唯一标识键。
`request_control_key` *	uuid4	客户请求的唯一标识键。
`payer_name` *	string	实际付款人姓名。
`payer_document_number` *	string	实际付款人的证件（CPF/CNPJ）。
`source_account_key` *	uuid4	被扣款账户的键。
`transaction_key` *	uuid4	付款交易的键。
`transaction_revert_key`	uuid4	付款冲销交易的键。
`paid_amount` *	number	实际付款金额。
`payment_date` *	string	付款日期。
`payment_type` *	enum	付款类型。
`bank_slip`	object	银行划账单。
`collection_slip`	object	收款单。
`payment_status` *	enum	付款状态。

Enumeradores payment_type

枚举值	类型	描述
`bank_slip`	string	银行划账单
`collection_slip`	string	收款单

注意

bank_slip 枚举值不适用于收款单流程，bank_slip 对象始终为 null。

Enumeradores payment_status

枚举值	描述
`pending_2fa_approval`	待双因素批准

Objeto collection_slip

字段	类型	描述
`barcode`	string	条形码。
`digitable_line`	string	可输入行。
`collection_name` *	string	协议名称。
`collection_document_number`	string	协议文件编号（CPF/CNPJ）。
`expiration_date` *	string	到期日期。
`total_amount` *	number	总金额。

Error Response

STATUS

4XX

Response Body

{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}

HTTP 代码	QI 代码	标题	描述（英文）	描述（葡文）
400	BIP000032	Bad Request	The bill sent does not correspond to a collection slip.	A conta enviada não corresponde a uma fatura de recolhimento.
400	BIP000033	Bad Request	The barcode or digitable line of the collection slip must have 44 or 48 characters.	O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres.
403	BIP000010	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BIP000011	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BIP000012	Bad Request	It was not possible to consult the source account at this time. Please try again in a few minutes.	Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000014	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
400	BIP000024	Bad Request	Request control key already exists.	Chave de controle da requisição já existe.
400	BIP000028	Bad Request	The source account has blocked balance. Payment cannot be made.	A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado.
400	BIP000034	Bad Request	Collection slip already paid.	Fatura de recolhimento já paga.
400	BIP000035	Bad Request	Covenant slip invalid barcode.	Código de barras da fatura de recolhimento inválido.
400	BIP000036	Bad Request	Covenant slip overdue.	Fatura de recolhimento vencida.
400	BIP000037	Bad Request	Error in collection slip consultation.	Erro na consulta da fatura de recolhimento.
400	BIP000038	Bad Request	Outside of covenant payment hours.	Fora do horário de pagamento do convênio.
400	BIP000039	Bad Request	Collection slip not accepted.	Fatura de recolhimento não aceita.
400	BIP000040	Bad Request	Minimum advance not reached.	Mínimo de dias de adiantamento não atingido.
400	BIP000041	Bad Request	Max payment amount exceeded.	Valor máximo de pagamento excedido.
400	BIP000044	Bad Request	It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance.	Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência.
403	BIP000052	Forbidden	Given document number does not belong to an approver for this account	Número de documento enviado não pertence a um aprovador da conta
400	BIP000053	Bad Request	Error getting approver data	Erro ao obter dados do aprovador
400	BIP000054	Bad Request	TFA info required	Informações de TFA necessárias
400	BIP000055	Bad Request	Error sending verification token	Erro ao enviar token de verificação
400	BIP000065	Bad Request	Payment verification time window exceeded.	Janela de tempo de verificação de pagamento excedida.
400	BIP000079	Bad Request	A session_id must be provided token	Uma session_id deve ser fornecida

Sandbox 环境

在我们的 sandbox 环境中，我们提供了模拟的可输入行，用于模拟成功付款和错误场景测试。

可输入行
828300000007411100972013905080001546763201900028
838000000009235700481007241345219112001474229880
848000000006308600802021201071261517689002201070
858200000015000000643025703477209504800448091020
858500000037350000643217212883260006147448091022

Request​

Request Endpoint​

Request Path Params​

通过邮件和短信认证​

通过设备认证​

Body Params​

Objeto tfa_info​

Response​

Success Response​

Response Body Params​

Enumeradores payment_type​

Enumeradores payment_status​

Objeto collection_slip​

Error Response​

Sandbox 环境​