- 集成指南
- 支持的功能（付款方式）
- Boleto Bancário
Boleto Bancário
Boleto Bancário，或简称 Boleto，是巴西一种安全、便捷的付款方式，付款人可以通过它以电子或现金方式支付商品和服务的费用。 付款人可以使用结账时发放的 Boleto 凭条或凭单，通过以下两种方式中的一种来付款： 通过网上银行，或打印 Boleto 凭条，在巴西全国范围内的某个注册位置使用现金付款。 付款人可以选择稍后付款，而不是在结账时付款，这样非常方便，同时您也可以放心，因为所有 Boleto Bancário 交易均受巴西中央银行的监管。
目前，Mastercard Gateway 仅支持使用 BRL 货币进行 Boleto Bancário 付款。
先决条件
如果您想向付款人提供 Boleto Bancário 作为付款方式：
- 您必须在 Boleto Bancário 的支付服务提供商处注册；例如，Citibank。
- Your payment service provider 必须在 Mastercard Gateway 上启用 Boleto Bancário 付款方式，并配置您的商家配置文件。
- 您必须有 your payment service provider 生成的唯一商家 ID，此 ID 将用于在 Mastercard Gateway 上处理 Boleto Bancário 交易。
Boleto Bancário 付款流
Boleto Bancário 付款方式的一般信息流程如下所述。
 |
支付服务提供商载入和注册。 支付服务提供商生成以下凭据： 基本编号、顺序编号和组合编号。 |
 |
使用步骤 1 中的凭据，your payment service provider 在 Mastercard Gateway 上载入并注册您的商家配置文件，并生成将提供给您的唯一商家 ID。 您将使用商家 ID 将 Boleto Bancário 交易提交到 Mastercard Gateway。 |
 |
付款人访问您的电子商务网站，进行购买，并在结账时选择 Boleto Bancário 作为付款方式。 |
 |
支付网关接收 API 请求来处理交易。 |
 |
Your payment service provider 向中央结算所注册 Boleto，生成一个条码编号和一个 47 位的序列号，然后将这些详细信息发送到支付网关。 |
 |
网关生成一个 Boleto 凭条或凭单，并在 API 响应中向您提供该条码编号和 47 位序列号。 此外，还将提供一个 URL，可以通过它下载或打印 Boleto 凭条。 |
 |
付款人使用 47 位序列号进行在线支付，或下载并打印 Boleto 凭条，在注册位置付款。 请注意，希望在注册位置付款的付款人必须能够下载或打印 Boleto 凭条。 |
您可以在两小时的时间范围内下载凭条。 如果您需要在有效期过后获取凭条，请联系 your payment service provider。
Boleto Bancário 作为 Hosted Checkout 的结账选项
如果您使用网关的付款页 (Hosted Checkout)，已在您的商家配置文件中配置了 Boleto Bancário，并且已在 Create Checkout Session 请求中将 Boleto 特定字段提交给网关，Boleto Bancário 将自动作为结账选项提供给您的付款人。
在使用 API 版本 58 或更高版本提交 Create Checkout Session 请求时，除了标准字段，还应提供以下字段：
| 字段 | 需要 | 描述 |
|---|---|---|
sourceOfFunds.provided.boletoBancario.dueDate |
是 | 指示需要支付 Boleto 金额的截止日期。 |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
否 | 付款人完成 Boleto 付款的 dueDate 过去之后，在执行 actionType 中指定的操作之前的宽限期。 |
sourceOfFunds.provided.boletoBancario.actionType |
否 | 付款未执行时要采取的行动。 |
order.invoiceNumber |
否 | 您为此订单分配的发票号。 如果您未提供值，网关将生成编号，在请求中提供。 |
在 Hosted Checkout 交互期间，如果付款人选择使用 Boleto Bancário 付款方式付款，则会显示以下字段：
- 客户类型： 付款人类型；例如，个人或公司。
- 客户名称/公司名称： 如果“客户类型”=“个人”，此字段为客户名称，如果“客户类型”=“公司”，则为公司名称。
- CPF/CNPJ： 这是政府分配的付款人标识符。 如果“客户类型”=“个人”，此字段为 Cadastro de Pessoas Fsicas (CPF)，如果“客户类型”=“公司”，则为 Cadastro Nacional de Pessoas Jurdicas (CNPJ)
| URL | https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/ |
| HTTP 方法 | POST |
{
"apiOperation": "CREATE_CHECKOUT_SESSION",
"interaction": {
"operation": "PURCHASE"
},
"order": {
"taxAmount": 100,
"amount": 749.99,
"currency": "BRL",
"id": "98098902948",
"invoiceNumber": "1234",
"taxRegistrationId": "12345678901",
"description": "I am using this....",
"item": [
{
"name": "Test Item 1",
"quantity": 1,
"unitPrice": "249.99"
},
{
"name": "Test Item 2",
"quantity": 1,
"unitPrice": "200"
},
{
"name": "Test Item 3",
"quantity": 1,
"unitPrice": "200"
}
]
},
"sourceOfFunds": {
"provided": {
"boletoBancario": {
"dueDate": "2020-03-02",
"daysBeforeAction": "4",
"actionType": "WRITE_OFF"
}
}
},
"billing": {
"address": {
"street": "street name",
"street2": "street name 2",
"city": "city",
"stateProvince": "MH",
"postcodeZip": "00411038"
}
},
"transaction": {
"reference": "12341234"
}
}
这里是一个成功的 Boleto Bancário 交易的示例响应，显示了请求中提交的所有详细信息，包含 Boleto 凭条的 URL。
| URL | https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP 方法 | GET |
{
"billing":{
"address":{
"city":"city",
"postcodeZip":"00411038",
"stateProvince":"MH",
"street":"street name",
"street2":"street name 2"
}
},
"browserPayment":{
"operation":"PAY"
},
"gatewayEntryPoint":"CHECKOUT",
"merchant":"TESTMERCH01",
"order":{
"amount":749.99,
"chargeback":{
"amount":0,
"currency":"BRL"
},
"creationTime":"2020-09-03T06:26:33.932Z",
"currency":"BRL",
"customerOrderDate":"2020-09-03",
"description":"I am using this....",
"id":"order12345",
"invoiceNumber":"1234",
"item":[
{
"name":"Test Item 1",
"quantity":1,
"unitPrice":249.99
},
{
"name":"Test Item 2",
"quantity":1,
"unitPrice":200
},
{
"name":"Test Item 3",
"quantity":1,
"unitPrice":200
}
],
"itemAmount":649.99,
"lastUpdatedTime":"2020-09-03T06:26:38.056Z",
"merchantAmount":749.99,
"merchantCurrency":"BRL",
"status":"INITIATED",
"taxAmount":100,
"taxRegistrationId":"12345678901",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0
},
"response":{
"acquirerCode":"0",
"acquirerMessage":"Data Received",
"gatewayCode":"SUBMITTED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"boletoBancario":{
"actionType":"WRITE_OFF",
"bankAccountHolder":"TESTCUSTOMERNAME",
"customerType":"INDIVIDUAL",
"daysBeforeAction":"4",
"dueDate":"2020-03-02",
"slipUrl":"https://example.com/bpui/cb/transaction/slip/BP-0d10be5954744203eb355a1be98bb190"
}
},
"type":"BOLETO_BANCARIO"
},
"timeOfLastUpdate":"2020-09-03T06:26:38.056Z",
"timeOfRecord":"2020-09-03T06:26:33.967Z",
"transaction":{
"acquirer":{
"additionalResponseData":"{\"barcode\":\"12345678901234567890123456789012000000000001\",\"digitableLine\":\"12345678901234567890123456789012345678901234567\"}",
"id":"CITIBR_1",
"merchantId":"12335522222233331234",
"transactionId":"order12345"
},
"amount":749.99,
"currency":"BRL",
"id":"1",
"item":[
{
"name":"Test Item 1",
"quantity":1,
"unitPrice":249.99
},
{
"name":"Test Item 2",
"quantity":1,
"unitPrice":200
},
{
"name":"Test Item 3",
"quantity":1,
"unitPrice":200
}
],
"receipt":"12345678901234567890123456789012000000000001",
"reference":"000012341234",
"source":"INTERNET",
"stan":"0",
"type":"PAYMENT"
},
"version":"60"
}
Boleto Bancário 作为付款页上的结账选项
如果您使用自己的付款页（参见 Direct Payment 集成），希望向付款人提供 Boleto Bancário 作为结账选项，则必须在 Pay 请求中提供以下字段。
提交 Pay 请求时，必须使用 API 版本 57 或更高版本。
交易请求
当付款人使用 Boleto Bancário 作为付款方式进行购买时，请向 Mastercard Gateway 提交 Pay 请求，并提供下表中所述的字段。
| 字段 | 需要 | 描述 |
|---|---|---|
sourceOfFunds.type |
是 | 指示付款人选择的付款方式。 将此字段的值设置为 BOLETO_BANCARIO。 |
customer.nationalId |
是 | 政府分配的付款人标识符。 例如，在巴西，可能是 Cadastro de Pessoas Fsicas (CPF) 或 Cadastro Nacional de Pessoas Jurdicas (CNPJ)。 必须提供此数字值（长度在 11 到 14 个数字之间），否则交易将被拒绝。 |
order.referencetransaction.acquirer.transactionId |
查看说明 | 如果您提供的 order.id 符合 Boleto 的验证规则，它将被用作订单参考。 否则，网关将生成并使用新参考。如果您希望为 Boleto 提供您自己的参考值，请在字段 transaction.acquirer.transactionId 中指定值。 如果不符合 Boleto 的验证规则，网关将拒绝交易。 无论何时，网关均会在 transaction.acquirer.transactionId 字段中返回使用的引用。 |
transaction.reference |
查看说明 | transaction.reference 字段是您或 your payment service provider 生成的每个 Boleto Bancário 交易的唯一标识符。Your payment service provider 将在载入过程中针对这两种方法中的一种配置您的配置文件。 如果您对为您配置的方法有任何疑问，我们建议您与他们联系。如果将由您生成交易标识符，则必须在每个交易的 transaction.reference 字段中将此标识符作为一个值提供。 否则，网关将拒绝交易。如果 your payment service provider 将生成交易标识符，那么，您不能提供此字段，否则网关将拒绝交易。 |
sourceOfFunds.provided.boletoBancario.bankAccountHolder |
是 | 付款人银行账户的银行账户所有人姓名。 |
sourceOfFunds.provided.boletoBancario.actionType |
否 | 付款未执行时要采取的行动。 |
sourceOfFunds.provided.boletoBancario.customerType |
否 | 付款人类型；例如，个人或公司。 此字段的默认值为 Individual。 |
sourceOfFunds.provided.boletoBancario.dueDate |
是 | 指示需要支付 Boleto 金额的截止日期。 |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
否 | 付款人完成 Boleto 付款的 dueDate 过去之后，在执行 actionType 中指定的操作之前的宽限期。 |
order.invoiceNumber |
查看说明 | 您为此订单分配的发票号。 如果您未提供值，网关将生成编号，在请求中提供。 |
order.taxAmount |
查看说明 | 订单的纳税金额。 如果您未提供值，网关会将其默认为零，并发送到下游系统。 order.amount 将等于请求中的 order.itemAmount。 |
交易响应
除非 Mastercard Gateway 返回 result=ERROR，否则响应将包含所有在 PAY 请求中提交的请求字段及其值。 此外，Mastercard Gateway 将返回下表中描述的详细信息。
| 字段 | 描述 |
|---|---|
response.acquirerCode |
指示交易注册成功或失败。 值 0（零）表示成功，值 99 表示失败。 |
response.acquirerMessage |
指示交易注册成功或失败的另一个消息。 如果注册成功，此字段将包含值 Data Received。 如果注册失败，此字段将包含值 Data Not Received。 |
response.gatewayCode |
指示操作成功或失败。 |
sourceOfFunds.provided.boletoBancario.slipUrl |
付款人可以访问 Boleto Bancário 凭条的 URL。 |
transaction.receipt |
交易注册成功时，此字段的值将包含用于在 Boleto 凭条上创建条码的 44 位数字。 如果付款人选择在注册位置向 Boleto 付款，供应商可以扫描此条码。 |
transaction.acquirer.additionalResponseData |
如果交易注册失败，此字段将包含错误代码和键值对格式的描述。 |
下面的 Boleto Bancário 交易的 PAY 请求示例包含到期日期，采取行动之前等待的天数，以及未在指定的到期日之前向 Boleto 付款时要采取的行动。
{
"apiOperation": "PAY",
"order": {
"amount": "669.99",
"itemAmount": "649.99"
"currency": "BRL",
"taxRegistrationId": "12345678901",
"reference": "01234568",
"taxAmount": "20",
"invoiceNumber": "0001230000",
},
"transaction": {
"merchantNote": "01456789012",
"reference": "01234567",
"acquirer": {
"transactionId": "01234568"
}
},
"billing": {
"address": {
"street": "Street 123",
"street2": "Business Way",
"city": "Pune",
"stateProvince": "MH",
"postcodeZip": "12345678"
}
},
"customer": {
"nationalId": "12345678901"
},
"sourceOfFunds": {
"type": "BOLETO_BANCARIO",
"provided": {
"boletoBancario": {
"customerType": "COMPANY",
"bankAccountHolder": "FIRSTNAME LASTNAME",
"dueDate": "2021-02-17",
"daysBeforeAction": "69",
"actionType": "WRITE_OFF"
}
}
}
}
以下 Boleto Bancário 交易响应示例显示了请求中提交的所有详细信息，并包含 Boleto 凭条的 URL。
{
"billing":{
"address":{
"city":"Pune",
"postcodeZip":"00411038",
"stateProvince":"MH",
"street":"YERWADA",
"street2":"Business Way"
}
},
"browserPayment":{
"operation":"PAY"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TESTCRMER01",
"order":{
"amount":763.99,
"chargeback":{
"amount":0,
"currency":"BRL"
},
"creationTime":"2021-02-23T07:54:25.464Z",
"currency":"BRL",
"customerOrderDate":"2021-02-23",
"discount":{
"amount":10.00
},
"id":"vp_528",
"invoiceNumber":"1230000",
"item":[
{
"name":"Korg MS-20 Mini",
"quantity":1,
"unitPrice":649.99
}
],
"itemAmount":649.99,
"lastUpdatedTime":"2021-02-23T07:54:33.993Z",
"merchantAmount":763.99,
"merchantCurrency":"BRL",
"reference":"12334",
"status":"INITIATED",
"taxAmount":124.00,
"taxRegistrationId":"12345678901",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0
},
"response":{
"acquirerCode":"0",
"acquirerMessage":"Data Received",
"gatewayCode":"SUBMITTED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"boletoBancario":{
"bankAccountHolder":"TEST",
"customerType":"COMPANY",
"daysBeforeAction":"4",
"dueDate":"2020-03-02",
"slipUrl":"https://dl01aspall4bv.mpgsdev.mastercard.int/bpui/cb/transaction/slip/BP-a7af97458dc12e0c57265d3bd886c4a8"
}
},
"type":"BOLETO_BANCARIO"
},
"timeOfLastUpdate":"2021-02-23T07:54:33.993Z",
"timeOfRecord":"2021-02-23T07:54:27.030Z",
"transaction":{
"acquirer":{
"additionalResponseData":"{\"barcode\":\"12345678901234567890123456789012000000000001\",\"digitableLine\":\"12345678901234567890123456789012345678901234567\"}",
"id":"CITIBR_1",
"merchantId":"12335522222233331234",
"transactionId":"12333"
},
"amount":763.99,
"currency":"BRL",
"id":"1",
"item":[
{
"name":"Korg MS-20 Mini",
"quantity":1,
"unitPrice":649.99
}
],
"merchantNote":"81",
"receipt":"12345678901234567890123456789012000000000001",
"reference":"000000000001",
"source":"INTERNET",
"stan":"0",
"type":"PAYMENT"
},
"version":"60"
}
下载或打印 Boleto 凭条
请务必注意，虽然 Mastercard Gateway 的响应中包含用于访问 Boleto 凭条的 URL，但是您的电子商务网站还必须支持付款人查看、下载或打印 Boleto 凭条。
例如，此功能可以是一个按钮，付款人可以在结账过程中单击它来查看和下载 Boleto 凭条。
测试您的集成
您可以使用测试商家配置文件（您的商家 ID，前缀为“TEST”）测试集成。 此部分提供可用于触发特定响应的 order.status 的详细信息。
在测试集成之前，请确保满足以下先决条件：
- 您已经向收单行注册。
- Your payment service provider 已使用您提供的以下信息在网关商家配置文件中设置了收单行链接：
- “基本编号”、“Cosmos 账号”和“组合编号”
- 有关谁将在交易中提供唯一交易识别码 (transaction.reference) 的信息 - 您或收单行。
- 您已通过在 Pay 请求中提供必需字段构建了集成。
| RESULT | order.status |
result |
response.gatewayCode |
response.acquirerCode |
|---|---|---|---|---|
| 成功 | INITIATED | SUCCESS | SUBMITTED | 0 |
| 失败 | FAILED | FAILURE | UNSPECIFIED_FAILURE | 99 |
| 超时 | FAILED | FAILURE | TIMED_OUT | N/A |