双因素身份验证银行票据支付请求

此端点用于发起银行票据支付请求。请求应在查询之后进行，使用返回的信息以确保流程正确运行，避免处理过程中出现错误。

银行票据

这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。

Request

请求端点

ENDPOINT

/account/ACCOUNT_KEY/payment/bank_slip

MÉTODO

POST

请求路径参数

字段	类型	描述	字符数
`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"
  }
}

通过设备验证

除了现有的 sms 和 email 验证方式外，还可以使用预先注册的设备对交易进行验证。在这种情况下，session_id 需从设备扫描获取并在 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 参数

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

警告

除非银行票据允许部分付款，否则 payment_amount 必须始终等于查询银行票据时返回的 total_amount。对于允许部分付款的票据，客户可以选择 payment_amount，但其与银行票据 registered_payment_amount 之和不得超过 total_amount。

tfa_info 对象

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

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

Response

成功响应

STATUS

201

Response Body: 支付待双因素审批

{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status":"pending_2fa_approval"
}

Response Body 参数

字段	类型	描述
`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	支付状态。

payment_type 枚举值

枚举值	类型	描述
`bank_slip`	string	银行票据
`collection_slip`	string	征税发票

警告

collection_slip 枚举值不适用于银行票据流程，同样 collection_slip 对象始终为空。

payment_status 枚举值

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

bank_slip 对象

字段	类型	描述
`barcode` *	string	条形码。
`digitable_line` *	string	数字行。
`payer_name` *	string	付款人名称。
`payer_document_number` *	string	付款人文件号码（CPF/CNPJ）。
`beneficiary_name` *	string	受益人名称。
`beneficiary_trading_name`	string	受益人商业名称。
`beneficiary_document_number` *	string	受益人文件号码（CPF/CNPJ）。
`beneficiary_bank_ispb` *	string	受益人银行 ISPB 代码。
`guarantor_name`	string	保证人名称。
`guarantor_document_number`	string	保证人文件号码（CPF/CNPJ）。
`expiration_date` *	string	到期日期。
`max_payment_date` *	string	最大支付日期。
`partial_payment_indicator` *	enum	部分付款指示符。
`registered_payment_amount`	string	已登记的总支付金额。
`nominal_amount` *	number	原始金额。
`total_amount` *	number	总金额。
`rebate_amount` *	number	折扣金额。
`discount_amount` *	number	优惠金额。
`fine_amount` *	number	罚款金额。
`interest_amount` *	number	利息金额。

partial_payment_indicator 枚举值

枚举值	类型	描述
`allowed`	string	允许
`not_allowed`	string	不允许

错误响应

STATUS

4XX

Response Body

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

HTTP 代码	QI 代码	标题	描述（英文）	描述（葡文）
400	BIP000001	Bad Request	The barcode or digitable line must have 44 or 47 characters.	O código de barras ou linha digitável deve ter 44 ou 47 caracteres.
400	BIP000002	Bad Request	The bill sent does not correspond to a bank slip.	A conta enviado não corresponde a um boleto bancário.
400	BIP000003	Bad Request	The digitable line sent is invalid.	A linha digitável enviada é inválida.
404	BIP000004	Not Found	The bank slip was not found.	O boleto não foi encontrado.
400	BIP000005	Bad Request	It was not possible to consult the bank slip at this time. Please try again in a few minutes.	Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos.
400	BIP000006	Bad Request	Bank slip already written off	Boleto já baixado
400	BIP000007	Bad Request	Bank slip blocked for payment	Boleto bloqueado para pagamento
400	BIP000008	Bad Request	Bank slip already paid	Boleto já pago
400	BIP000009	Bad Request	Invalid bank slip. Please consult issuing bank	Boleto inválido. Favor consultar banco emissor
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	BIP000015	Bad Request	Payment date is greater than the maximum payment date.	A data de pagamento é maior que a data máxima de pagamento.
400	BIP000016	Bad Request	Payment date is smaller than the calculation date.	A data de pagamento é menor que a data de cálculo.
400	BIP000017	Bad Request	Invalid payment amount.	Valor de pagamento inválido.
400	BIP000018	Bad Request	Partial payment is not allowed.	Pagamento parcial não é permitido.
400	BIP000019	Bad Request	The payment amount is greater than the available amount.	O valor do pagamento é maior que o valor disponível.
400	BIP000020	Bad Request	All partial payments for this bank slip have already been made.	Todos os pagamentos parciais deste boleto já foram realizados.
400	BIP000024	Bad Request	Request control key already exists.	Chave de controle da requisição já existe.
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

沙盒环境

在我们的沙盒环境中，我们提供模拟的数字行用于模拟成功支付和错误场景测试。

数字行
00190000090361557400500000024174396700000991000
00190000090282802601919212747174596760001294161
23793390014000000455277000249001596900000103995
75691434020137513680900001040013196770002417240
21390001171200000570700168167484796770000148206
34191090083273252027893634770007296690012513600
42297048060005815702500130494123896770000239491
07090010287045349010776686070590896770001160123
74891123702849020818918378871083196690000050000
23792374119000209350986000372408496610000122810

Request​

请求端点​

请求路径参数​

通过电子邮件和短信验证​

通过设备验证​

Body 参数​

tfa_info 对象​

Response​

成功响应​

Response Body 参数​

payment_type 枚举值​

payment_status 枚举值​

bank_slip 对象​

partial_payment_indicator 枚举值​

错误响应​

沙盒环境​