Banco do Brasil · e-SiTef

This document describes the integration with Banco do Brasil payment platform, as well as explaining about the configurations that must necessarily be made on e-SiTef environment.

Supported e-SiTef interfaces

The merchant can use the following e-SiTef services for integration with Banco do Brasil (the respective documents must be consulted for further details):

HTML Payment Interface
Reissue of Boletos

e-SiTef required configurations

Before making Banco do Brasil transactions with e-SiTef, 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 e-SiTef 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 e-SiTef 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 e-SiTef

Having the Banco do Brasil account data above, the merchant must request to e-SiTef support team:

The registration of Banco do Brasil as an active authorizer on e-SiTef.
If the merchant doesn’t have them yet, a username and a password to the e-SiTef 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 e-SiTef

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 e-SiTef 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 e-SiTef 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

e-SiTef 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 e-SiTef transaction parameters + Banco do Brasil data (additional_data) in JSON format:

{
   "merchant_id":"CODIGO_LOJA",
   "order_id":"1123456",
   "redirect":"M",
   "authorizer_id":"404",
   "amount":"2000",
   "installments":"1",
   "back_url":{
      "url_success":"url relativa de sucesso cadastrada no e-SiTef",
      "url_failure":" url relativa de fracasso cadastrada no e-SiTef",
      "url_cancel":" url relativa de cancelameto cadastrada no e-SiTef"
   },
   "additional_data":{
      "payer":{
         "name":"Paul",
         "surname":"Smith",
         "address_street_name":"Elma Street",
         "address_street_number":"123",
         "address_street_complement":"ap. 11",
         "city":"Sao Paulo",
         "address_zip_code":"01230120",
         "state":"SP"
      }
   }
}