- Pautas de integración
- Características soportadas (métodos de pago)
- Boleto Bancário
Boleto Bancário
Boleto Bancário, o simplemente Boleto, es un método de pago seguro y conveniente en Brasil que permite a los pagadores realizar pagos electrónicos o en efectivo por bienes y servicios. Los pagadores pueden utilizar el recibo o comprobante de Boleto que se emite al finalizar el pedido para realizar el pago de una de estas dos formas: a través de su banco en línea o imprimiendo el recibo de Boleto y pagando en efectivo en una ubicación registrada en todo Brasil. Los pagadores tienen la cómoda opción de pagar más tarde en lugar de al finalizar el pedido, mientras que usted tiene la tranquilidad de saber que todas las transacciones de Boleto Bancário están reguladas por el Banco Central de Brasil.
Actualmente, Mastercard Gateway solo admite pagos de Boleto Bancário en moneda BRL.
Prerrequisitos
Si desea ofrecer Boleto Bancário como método de pago a sus pagadores:
- Debe estar registrado con un proveedor de pagos para Boleto Bancário; por ejemplo, Citibank.
- Your payment service provider debe habilitar el método de pago de Boleto Bancário y configurar su perfil de negocio en Mastercard Gateway.
- Debe tener el identificador de negocio único generado por your payment service provider, que se utilizará para procesar las transacciones de Boleto Bancário en Mastercard Gateway.
Flujo de pago del Boleto Bancário
El flujo de información general del método de pago Boleto Bancário se describe a continuación.
 |
Incorporación y registro con el proveedor de pagos. El proveedor de pagos genera las siguientes credenciales: número de base, número de cosmos y número de cartera. |
 |
Con las credenciales del paso 1, el your payment service provider incorpora y registra su perfil de negocio en Mastercard Gateway y genera un identificador de negocio único que le proporcionará. Usted utilizará el ID de negocio para enviar transacciones de Boleto Bancário a Mastercard Gateway. |
 |
El pagador visita su sitio web de comercio electrónico, realiza una compra y selecciona Boleto Bancário como método de pago al finalizar la compra. |
 |
El motor de pagos recibe la solicitud de la API para procesar la transacción. |
 |
Your payment service provider registra un Boleto en la cámara de compensación central, genera un número de código de barras y un número de serie de 47 dígitos y envía estos detalles al motor de pagos. |
 |
El motor de pagos genera un recibo o comprobante de Boleto y le proporciona el número de código de barras y el número de serie de 47 dígitos en la respuesta de la API. Además, se proporciona una dirección URL desde donde se puede descargar o imprimir el recibo de Boleto. |
 |
El pagador realiza un pago en línea utilizando el número de serie de 47 dígitos o descarga e imprime el recibo de Boleto para pagar en una ubicación registrada. Tenga en cuenta que los pagadores que deseen pagar en una ubicación registrada deben tener la posibilidad de descargar o imprimir el recibo de Boleto. |
Puede descargar el recibo en un plazo de dos horas. Si desea acceder al recibo después del período de validez, póngase en contacto con your payment service provider.
Boleto Bancário como opción de pago en Hosted Checkout
Si utiliza la página de pago del motor de pagos (Hosted Checkout), Boleto Bancário se ofrecerá automáticamente como opción de pago a sus pagadores si Boleto Bancário se ha configurado en su perfil de negocio, y los campos específicos de Boleto se han enviado al motor de pagos en la solicitud Create Checkout Session.
Además de los campos estándar, proporcione los siguientes campos cuando envíe una solicitud Create Checkout Session utilizando la API versión 58 o superior:
| Campo | Obligatorio | Descripción |
|---|---|---|
sourceOfFunds.provided.boletoBancario.dueDate |
Sí | Indica la fecha en la que se debe pagar el monto de Boleto. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
No | El período de gracia después de que haya transcurrido la dueDate para que el pagador realice el pago mediante Boleto y antes de que se lleve a cabo la acción especificada en actionType. |
sourceOfFunds.provided.boletoBancario.actionType |
No | La medida que se va a tomar si el pago no se cumple. |
order.invoiceNumber |
No | El número de factura que emitió para este pedido. Si no proporciona ningún valor, el motor de pagos generará el número y lo proporcionará en la solicitud. |
Durante la interacción de Hosted Checkout, se muestran los siguientes campos si el pagador elige pagar utilizando el método de pago Boleto Bancário:
- Tipo de cliente: el tipo de pagador; por ejemplo, una persona o una empresa.
- Nombre del cliente/Nombre de la empresa: si Tipo de cliente = Persona, este será el nombre del cliente, mientras que si Tipo de cliente = Empresa, este será el nombre de la empresa.
- CPF/CNPJ: identificador del pagador asignado por el gobierno. Si Tipo de cliente = Persona, será Cadastro de Pessoas F-sicas (CPF), mientras que si Tipo de cliente = Empresa, será Cadastro Nacional de Pessoas Jur-dicas (CNPJ).
| URL | https://secure.eu.tnspayments.com/api/rest/version/72/merchant/{merchantId}/session/ |
| Método 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"
}
}
A continuación se muestra un ejemplo de respuesta de una transacción exitosa de Boleto Bancário que muestra todos los detalles que se enviaron en la solicitud e incluye la URL del comprobante de Boleto.
| URL | https://secure.eu.tnspayments.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Método 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 como opción de pago en su página de pago
Si utiliza su propia página de pago (consulte Integración de Direct Payment) y desea ofrecer Boleto Bancário como opción de pago a sus pagadores, debe proporcionar los siguientes campos en la solicitud Pay.
Al enviar la solicitud Pay, debe utilizar la versión de la API 57 o superior.
Solicitud de transacción
Cuando un pagador realice una compra utilizando Boleto Bancário como método de pago, envíe una solicitud Pay a Mastercard Gateway y proporcione los campos que se describen en la siguiente tabla.
| Campo | Obligatorio | Descripción |
|---|---|---|
sourceOfFunds.type |
Sí | Indica el método de pago seleccionado por el pagador. Establezca el valor de este campo en BOLETO_BANCARIO. |
customer.nationalId |
Sí | Identificador del pagador asignado por el gobierno. Por ejemplo, en Brasil podría ser el Cadastro de Pessoas Físicas (CPF) o el Cadastro Nacional de Pessoas Jurídicas (CNPJ). Se debe proporcionar este valor numérico de entre 11 y 14 números de longitud, de lo contrario se rechaza la transacción. |
order.referencetransaction.acquirer.transactionId |
Consulte la descripción | Si el order.id que proporcione cumple con las reglas de validación de Boleto, entonces se utiliza como referencia del pedido. De lo contrario, el motor de pagos genera y utiliza una referencia nueva.Si desea proporcionar su propio valor de referencia a Boleto, especifique el valor en el campo transaction.acquirer.transactionId. Si no cumple con las reglas de validación de Boleto, el motor de pagos rechaza la transacción. En todos los casos, el motor de pagos devuelve la referencia que se usó en el campo transaction.acquirer.transactionId. |
transaction.reference |
Consulte la descripción | El campo transaction.reference es un identificador único de cada transacción de Boleto Bancário, generado por usted o por your payment service provider. Your payment service provider configurará su perfil para uno de estos dos métodos durante el proceso de incorporación. Le recomendamos que se ponga en contacto con ellos si tiene alguna pregunta sobre qué método se ha configurado para usted.Si va a generar el identificador de transacción, debe proporcionarlo como valor en el campo transaction.reference para cada transacción. De lo contrario, el motor de pagos rechaza la transacción.Si your payment service provider va a generar el identificador de la transacción, no se debe proporcionar el campo; de lo contrario, el motor de pagos rechazará la transacción. |
sourceOfFunds.provided.boletoBancario.bankAccountHolder |
Sí | El nombre del titular de la cuenta bancaria para la cuenta bancaria del pagador. |
sourceOfFunds.provided.boletoBancario.actionType |
No | La medida que se va a tomar si el pago no se cumple. |
sourceOfFunds.provided.boletoBancario.customerType |
No | El tipo de pagador; por ejemplo, una persona o una empresa. El valor predeterminado es Persona. |
sourceOfFunds.provided.boletoBancario.dueDate |
Sí | Indica la fecha en la que se debe pagar el monto de Boleto. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
No | El período de gracia después de que haya transcurrido la dueDate para que el pagador realice el pago mediante Boleto y antes de que se lleve a cabo la acción especificada en actionType. |
order.invoiceNumber |
Consulte la descripción | El número de factura que emitió para este pedido. Si no proporciona ningún valor, el motor de pagos generará el número y lo proporcionará en la solicitud. |
order.taxAmount |
Consulte la descripción | El monto total de impuestos del pedido. Si no proporciona ningún valor, el motor de pagos lo establecerá de forma predeterminada en cero y lo enviará al sistema para su posterior procesamiento. El valor de order.amount será igual al de order.itemAmount en la solicitud. |
Respuesta de la transacción
A menos que Mastercard Gateway devuelva result=ERROR, la respuesta incluye todos los campos de solicitud y sus valores que se enviaron en la solicitud PAY. Además, Mastercard Gateway devuelve los detalles descritos en la siguiente tabla.
| Campo | Descripción |
|---|---|
response.acquirerCode |
Indica si el registro de la transacción fue correcto o falló. Un valor de 0 (cero) indica que fue correcto y un valor de 99 indica que falló. |
response.acquirerMessage |
Un mensaje adicional que indica si el registro de la transacción fue correcto o falló. Si el registro fue correcto, este campo contiene el valor Data Received (Datos recibidos). Si el registro falló, este campo contiene el valor Data Not Received (Datos no recibidos). |
response.gatewayCode |
Indica si la operación fue correcta o falló. |
sourceOfFunds.provided.boletoBancario.slipUrl |
La URL donde el pagador puede acceder al comprobante del Boleto Bancário. |
transaction.receipt |
Cuando el registro de una transacción se realiza correctamente, el valor de este campo contiene el número de 44 dígitos que se utilizó para crear el código de barras en el recibo de Boleto. El proveedor puede escanear este código de barras si un pagador opta por pagar el Boleto en una ubicación registrada. |
transaction.acquirer.additionalResponseData |
Si el registro de la transacción falla, este campo contiene un código de error y una descripción en formato de par clave-valor. |
El siguiente ejemplo de solicitud PAY de una transacción de Boleto Bancário incluye la fecha de vencimiento, los días antes de que se emprenda una acción y qué acción se debe emprender si el Boleto no se paga en la fecha de vencimiento especificada.
{
"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"
}
}
}
}
El siguiente ejemplo de respuesta de una transacción de Boleto Bancário muestra todos los detalles que se enviaron en la solicitud e incluye la URL del comprobante de Boleto.
{
"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"
}
Descargar o imprimir el comprobante de Boleto
Es importante señalar que, aunque la respuesta de Mastercard Gateway incluye la dirección URL para acceder al recibo de Boleto, su sitio web de comercio electrónico debe permitir a sus pagadores ver, descargar o imprimir el recibo de Boleto.
Por ejemplo, esta funcionalidad puede ser un botón en el que sus pagadores pueden hacer clic para ver y descargar el recibo de Boleto durante el proceso de pago.
Prueba de su integración
Puede probar su integración utilizando su perfil de pruebas del negocio (su ID de negocio con el prefijo "TEST"). Esta sección ofrece detalles sobre el valor de order.status que se puede utilizar para desencadenar una respuesta específica.
Antes de probar la integración, asegúrese de que se cumplan los siguientes prerrequisitos:
- Se le ha incorporado al adquirente.
- Your payment service provider ha configurado el vínculo de adquirente en su perfil del negocio del motor de pagos utilizando la siguiente información proporcionada por usted:
- "Número base", "Número de cuenta Cosmos" y "Número de cartera"
- Información sobre quién proporcionará el identificador de transacción único (transaction.reference) en la transacción: usted o el adquirente.
- Ha creado la integración proporcionando los campos obligatorios en la solicitud Pay.
| RESULT | order.status |
result |
response.gatewayCode |
response.acquirerCode |
|---|---|---|---|---|
| Con éxito | INITIATED | SUCCESS | SUBMITTED | 0 |
| Falla | FAILED | FAILURE | UNSPECIFIED_FAILURE | 99 |
| Tiempo de espera | FAILED | FAILURE | TIMED_OUT | N/A |