Banco do Brasil
This document describes the integration with Banco do Brasil payment platform, as well as explaining about the configurations that must necessarily be made on Carat Portal environment.
Supported Carat Portal interfaces#
The merchant can use the following Carat Portal services for integration with Banco do Brasil (the respective documents must be consulted for further details):
- HTML Payment Interface
- Reissue of Boletos
Carat Portal required configurations#
Before making Banco do Brasil transactions with Carat Portal, the configuration steps below must be followed:
Banco do Brasil’s account data#
The Merchant must have an active account on Banco do Brasil.
The following table shows Banco do Brasil credentials that must be retrieved by the merchant, which will be registered on Carat Portal later:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
| idConvComercio | Electronic Commerce Agreement Id on Banco do Brasil | 6 N | YES |
| idConvCobranca | Billing Agreement Id on Banco do Brasil | < 7 N | YES |
| diasVencimento | The number of days that must be added to the generation date of the boleto that will result in the expiration date of the boleto. | N | YES |
| mensagem_boleto | Message that will be displayed in the observation area of the boleto generated. | < 480 N | NO |
It is also necessary to configure some data related to Carat Portal on the merchant's account on the Banco do Brasil portal:
Values during Homologation environment:
URL de Retorno: https://esitef-homologacao.softwareexpress.com.br
URL de Informação: https://esitef-homologacao.softwareexpress.com.br
Once the approval is finalized and the merchant is activated on production, the registered values must be modified:
Values for the Production environment:
URL de Retorno: https://esitef-ec.softwareexpress.com.br
URL de Informação: https://esitef-ec.softwareexpress.com.br
Insert account data on Carat Portal#
Having the Banco do Brasil account data above, the merchant must request to Carat Portal support team:
- The registration of Banco do Brasil as an active authorizer on Carat Portal.
- If the merchant doesn’t have them yet, a username and a password to the Carat Portal Merchant’s Portal.
As soon as the Banco do Brasil authorizer is associated with the merchant, the Merchant’s Portal must be accessed to inform Banco do Brasil’s account data in the "Configuração de Autorizadoras" (Authorizers Configuration) menu, with the parameters idConvComercio, idConvCobranca, diasVencimento, mensagem_boleto mentioned above.
For further details on how to register these data on the Merchant’s Portal, please see Merchant's Portal - Configure Authorizers.
Authorizer code for Banco do Brasil on Carat Portal#
To make payments with the pre-defined authorizer, send one of the following authorizer id's referring to Banco do Brasil:
- 404 - Boleto
- 415 - Debit PF
- 416 - Debit PF and PJ
- 417 - Crediário
HTML Payment Interface#
For the initial flow to start an HTML transaction on Carat Portal with Banco do Brasil, please see the HTML Payment item.
Note: Data related to installments are not sent to Banco do Brasil.
Attention: When generating a boleto with the authorizer Banco do Brasil, the transaction final status will be Processed (PRO). It does NOT mean that the Boleto has already been paid, but only that the BNOToleto was issued. This behavior is due to the lack of tools for such verification by Banco do Brasil.
Parameters for transaction via Banco do Brasil#
Listed below are the JSON parameters that the merchant can send to Carat Portal to enable the customer to make a payment on Banco do Brasil.
additional_data Object#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
| discount_amount | Discount amount in cents. Used only for boleto. | < 12 N | NO |
| discount_limit_date | Discount limit date in DDMMYYYY format. Used only for boleto. | 8 N | NO |
| duplicata_type | Duplicata type: DM - Duplicata Mercantil; DS - Duplicata de serviços. | 2 A | YES¹ |
- ¹ Mandatory for Boleto.
additional_data.payer Object#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
| name | Payer name | AN² | YES |
| surname | Payer surname | AN² | YES |
| address_street_name | Payer address | AN³ | YES |
| address_street_number | Payer address number | AN³ | YES |
| address_street_complement | Payer address complement | AN³ | YES |
| address_zip_code | Payer address zip code | 8 N | YES |
| city | Payer city | < 18 A | YES |
| state | Payer state | < 2 A | YES |
| identification_number | Customer’s document (CPF or CNPJ), without formatting. | < 14 N | YES¹ |
| identification_type | Indicates that the identification_number field represents: 1 - PF 2 - PJ | 1 N | YES¹ |
¹ Mandatory for boleto.
² The size of the name plus the surname fields cannot be greater than 59 characters. A spacing character between fields will result in 60 characters.
³ The size of address_street_name, plus address_street_number, plus address_street_complement fields cannot be greater than 58 characters. A spacing character between these fields will result in 60 characters.
Note: The sizes of the fields are following the documentation provided by Banco do Brasil.
Banco do Brasil Payment Flow#
After sending the transaction creation data and choosing the Banco do Brasil payment method, the following flow of screens will be started:
The following image shows the screen before the buyer redirection.
The next image shows the next screen, where the payment is performed on Banco do Brasil:
Reissue of Boletos#
Carat Portal provides the reissue of Banco do Brasil Boletos. To do this, simply redirect the customer to the following URL:
https://esitef-homologacao.softwareexpress.com.br/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
(Homologation environment)https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
(Production environment)
The nit parameter is mandatory and must be associated to a payment transaction with status Processed (PRO) with the Banco do Brasil authorizer.
If the payment transaction is not in the expected status, the following screen is displayed:
The simple access to this URL already allows the direct visualization of the boleto reissued with the same data of the first emission, as in the image bellow:
HTML Payment request example#
Endpoint URL in Homologation environment:
https://esitef-homologacao.softwareexpress.com.br/e-sitef/init.se
Example of Carat Portal transaction parameters + Banco do Brasil data (additional_data) in JSON format: