Boleto Bancário
Boleto Bancário, or simply Boleto, is a safe and convenient payment method in Brazil that enables payers to make electronic or cash payments for goods and services. Payers can use the Boleto slip or voucher that is issued at checkout to make the payment one of two ways: through their online bank, or by printing the Boleto slip and paying in cash at a registered location throughout Brazil. Payers have the convenient option of paying later rather than at checkout, while you have peace of mind knowing that all Boleto Bancário transactions are regulated by the Central Bank of Brazil.
Currently, the Mastercard Gateway only supports Boleto Bancário payments in BRL currency.
Prerequisites
If you want to offer Boleto Bancário as a payment method to your payers:
- You must be registered with a payment provider for Boleto Bancário; for example, Citibank.
- Your payment service provider must enable the Boleto Bancário payment method and configure your merchant profile on the Mastercard Gateway.
- You must have the unique merchant ID generated by your payment service provider, which will be used to process Boleto Bancário transactions on the Mastercard Gateway.
Boleto Bancário Payment Flow
The general information flow of the Boleto Bancário payment method is described below.
 |
Onboarding and registration with payment provider. The payment provider generates the following credentials: base number, cosmos number, and portfolio number. |
 |
Using the credentials from step 1, your payment service provider onboards and registers your merchant profile on the Mastercard Gateway and generates a unique merchant ID that they will provide to you. You will use the merchant ID to submit Boleto Bancário transactions to the Mastercard Gateway. |
 |
The payer visits your e-commerce website, makes a purchase, and selects Boleto Bancário as the payment method at checkout. |
 |
The payment gateway receives the API request to process the transaction. |
 |
Your payment service provider registers a Boleto with the central clearing house, generates a bar code number and a 47 digit serial number, and sends these details to the payment gateway. |
 |
The gateway generates a Boleto slip or voucher, and provides you the bar code number and the 47 digit serial number in the API response. In addition, a URL is provided from where the Boleto slip can be downloaded or printed. |
 |
The payer either makes an online payment using the 47 digit serial number, or they download and print the Boleto slip to pay at a registered location. Note that payers wanting to pay at a registered location must have the ability to download or print the Boleto slip. |
You can download the slip in the two-hour time frame. If you want to access the slip after
the validity period, contact your payment service provider.
Boleto Bancário as a checkout option in Hosted Checkout
If you are using the gateway's payment page (Hosted Checkout), Boleto Bancário will automatically be offered as a checkout option to your payers if Boleto Bancário has been configured on your merchant profile, and Boleto-specific fields have been submitted to the gateway in the Create Checkout Session request.
In addition to the standard fields, provide the following fields when you submit a Create Checkout Session request using API version 58 or above:
| Field | Required | Description |
|---|---|---|
sourceOfFunds.provided.boletoBancario.dueDate |
Yes | Indicates the date by which the Boleto amount needs to be paid. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
No | The grace period after the dueDate has passed for the payer to make the Boleto payment and before the action specified in actionType is taken. |
sourceOfFunds.provided.boletoBancario.actionType |
No | The action to take if the payment is not honored. |
order.invoiceNumber |
No | The invoice number you issued for this order. If you do not provide a value, the gateway will generate the number and provide it in the request. |
During the Hosted Checkout interaction, the following fields are displayed if the payer chooses to pay using the Boleto Bancário payment method:
- Customer Type: The type of payer; for example, an individual or a company.
- Customer Name/Company Name: If Customer Type=Individual, this will be the customer name whereas if Customer Type=Company this will be the company name.
- CPF/CNPJ: This is the payer's government assigned identifier. If Customer Type=Individual, this will be Cadastro de Pessoas Físicas (CPF) whereas if Customer Type=Company this will be the Cadastro Nacional de Pessoas Jurídicas (CNPJ)
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/ |
| HTTP Method | 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"
}
}
Here's an example response of a successful Boleto Bancário transaction showing all details that were submitted in the request, and includes the URL to the Boleto slip.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP Method | 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 as a checkout option on your payment page
If you are using your own payment page (see Direct Payment integration) and want to offer Boleto Bancário as a checkout option to your payers, you must provide the following fields in the Pay request.
You must use API version 57 or above when you submit the Pay request.
Transaction request
When a payer makes a purchase using Boleto Bancário as the payment method, submit a Pay request to the Mastercard Gateway and provide the fields as described in the following table.
| Field | Required | Description |
|---|---|---|
sourceOfFunds.type |
Yes | Indicates the payment method selected by the payer. Set the value of this field to BOLETO_BANCARIO. |
customer.nationalId |
Yes | The payer's government assigned identifier. For example, in Brazil this could be the Cadastro de Pessoas Físicas (CPF) or Cadastro Nacional de Pessoas Jurídicas (CNPJ). This numeric value between 11 and 14 numbers in length must be provided, otherwise the transaction is rejected. |
order.referencetransaction.acquirer.transactionId |
See description | If the order.id that you provide conforms to Boleto's validation rules, then it is used as the order reference. Otherwise, a new reference is generated and used by the gateway.If you want to provide your own reference value to Boleto, specify the value in the field transaction.acquirer.transactionId. If it does not meet Boleto's validation rules, the gateway rejects the transaction. In all cases, the gateway returns the reference that was used in the transaction.acquirer.transactionId field. |
transaction.reference |
See description | The transaction.reference field is a unique identifier of each Boleto Bancário transaction, generated by you or your payment service provider. Your payment service provider will configure your profile for one of these two methods during the onboarding process. We recommend that you contact them if you have any questions regarding which method has been configured for you.If you are to generate the transaction identifier, you must provide it as a value in the transaction.reference field for each transaction. Otherwise, the gateway rejects the transaction.If your payment service provider is to generate the transaction identifier, then you must not provide the field else the gateway rejects the transaction. |
sourceOfFunds.provided.boletoBancario.bankAccountHolder |
Yes | The name of the bank account holder for the payer's bank account. |
sourceOfFunds.provided.boletoBancario.actionType |
No | The action to take if the payment is not honored. |
sourceOfFunds.provided.boletoBancario.customerType |
No | The type of payer; for example, an individual or a company. The default value is Individual. |
sourceOfFunds.provided.boletoBancario.dueDate |
Yes | Indicates the date by which the Boleto amount needs to be paid. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
No | The grace period after the dueDate has passed for the payer to make the Boleto payment and before the action specified in actionType is taken. |
order.invoiceNumber |
See description | The invoice number you issued for this order. If you do not provide a value, the gateway will generate the number and provide it in the request. |
order.taxAmount |
See description | The total tax amount for the order. If you do not provide a value, the gateway will default it to zero and send it to the downstream system. The order.amount will be equal to the order.itemAmount in the request. |
Transaction Response
Unless the Mastercard Gateway returns result=ERROR, the response includes all request fields and their values that were submitted in the PAY request. In addition, the Mastercard Gateway returns the details described in the following table.
| Field | Description |
|---|---|
response.acquirerCode |
Indicates success or failure of the transaction registration. A value of 0 (zero) indicates success, and a value of 99 indicates failure. |
response.acquirerMessage |
An additional message indicating the success or failure of the transaction registration. If the registration was successful, this field contains the value Data Received. If the registration failed, this field contains the value Data Not Received. |
response.gatewayCode |
Indicates success or failure of the operation. |
sourceOfFunds.provided.boletoBancario.slipUrl |
The URL where the payer can access the Boleto Bancário slip. |
transaction.receipt |
When a transaction registration succeeds, the value of this field contains the 44-digit number that was used to create the bar code on the Boleto slip. This bar code can then be scanned by the vendor if a payer elects to pay Boleto at a registered location. |
transaction.acquirer.additionalResponseData |
If the transaction registration fails, this field contains an error code and a description in key-value pair format. |
The following PAY request example of a Boleto Bancário transaction includes the due date, the days before action is taken, and what action to take if the Boleto is not paid by the specified due date.
{
"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"
}
}
}
}
The following response example of a Boleto Bancário transaction shows all details that were submitted in the request, and includes the URL to the Boleto slip.
{
"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"
}
Downloading or printing Boleto slip
It is important to note that although the Mastercard Gateway's response includes the URL to access the Boleto slip, your e-commerce website must enable your payers to view, download, or print the Boleto slip.
For example, this functionality can be a button that your payers can click to view and download the Boleto slip during the checkout process.
Testing your integration
You can test your integration using your test merchant profile (your merchant ID prefixed with "TEST"). This section provides details about the order.status that can be used to trigger a specific response.
Before you test your integration, ensure the following prerequistes have been met:
- You have been on-boarded with the acquirer.
- Your payment service provider has set up the acquirer link on your gateway merchant profile using the following information as provided by you:
- "Base Number", "Cosmos Account Number" and "Portfolio Number"
- Information on who will be providing the unique transaction identifier (transaction.reference) in the transaction — you or the acquirer.
- You have built your integration by providing the required fields in the Pay request.
| RESULT | order.status |
result |
response.gatewayCode |
response.acquirerCode |
|---|---|---|---|---|
| Successful | INITIATED | SUCCESS | SUBMITTED | 0 |
| Failure | FAILED | FAILURE | UNSPECIFIED_FAILURE | 99 |
| Time out | FAILED | FAILURE | TIMED_OUT | N/A |