Banco do Brasil
Esta documentação descreve a integração com a plataforma de pagamento Banco do Brasil. Além de explicar, também, sobre as configurações que devem ser, necessariamente, efetuadas no ambiente do Carat.
Interfaces Carat suportadas para integração#
A loja pode utilizar os seguintes serviços do Carat para a integração com a plataforma Banco do Brasil (os respectivos documentos devem ser consultados para mais detalhes):
- Interface de Pagamento HTML
- Reemissão de Boletos
Configurações necessárias no Carat#
Antes de efetuar transações Banco do Brasil com o Carat, devem ser seguidos os passos de configuração apresentados a seguir.
Dados Cadastrais do Banco do Brasil#
A loja deve possuir uma conta ativa com o Banco do Brasil para realizar uma transação.
A tabela a seguir mostra as credenciais Banco do Brasil que devem ser obtidas pela loja e dados adicionais a serem inseridos no boleto, e que posteriormente serão cadastradas no Carat:
| Nome do parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| idConvComercio | Identificador de Convênio de Comércio Eletrônico no Banco do Brasil | 6 N | SIM |
| idConvCobranca | Identificador de Convênio de Cobrança no Banco do Brasil | < 7 N | SIM |
| diasVencimento | Quantidade de dias que deverá ser somado à data da geração do boleto que resultará na data de vencimento do boleto. | N | SIM |
| mensagem_boleto | Mensagem que será exibida na área de observações do boleto gerado. | < 480 N | NÃO |
É necessário também que sejam configurados no portal do Banco do Brasil, na conta do cliente, alguns dados referentes ao Carat:
Valores durante a etapa de Homologação:
URL de Retorno: https://{{url}}
URL de Informação: https://{{url}}
Assim que a homologação for finalizada e a loja for ativada em produção, os valores cadastrados devem ser modificados:
Valores para ambiente de Produção:
URL de Retorno: https://esitef-ec.softwareexpress.com.br
URL de Informação: https://esitef-ec.softwareexpress.com.br
Inserir dados cadastrais no Carat#
Tendo em mãos os dados cadastrais do Banco do Brasil citados acima, o lojista deve solicitar à equipe de atendimento do Carat:
- A ativação do Banco do Brasil como uma autorizadora ativa no cadastro do Carat.
- Caso não possua, um usuário e senha de acesso ao Portal do Lojista no Carat.
Assim que a autorizadora Banco do Brasil estiver associada à loja, o lojista deve acessar o Portal do Lojista e informar os dados cadastrais do Banco do Brasil no item Configuração de Autorizadoras, com os parâmetros idConvComercio, idConvCobranca, diasVencimento, mensagem_boleto citados anteriormente.
Para mais detalhes de como cadastrar estes dados no portal do lojista, por favor, consulte o item sobre o Portal do Lojista - Configuração de Autorizadoras.
Código de Autorizadora para Banco do Brasil no Carat#
Para realizar pagamentos com a autorizadora pré-definida, envie um dos seguintes id's de autorizadora referentes ao Banco do Brasil:
- 404 - Boleto
- 415 - Débito PF
- 416 - Débito PF e PJ
- 417 - Crediário
Parâmetros para Pagamento HTML via Banco do Brasil#
Sobre o fluxo inicial para iniciar uma transação HTML no Carat com o Banco do Brasil, consulte o item sobre o Pagamento HTML.
Observação: Dados referentes a parcelamento não são repassados ao Banco do Brasil.
Atenção: Transações realizadas com a autorizadora Banco do Brasil, quando o cliente tiver optado pela geração de um boleto, terão seu status final como Processado (PRO), NÃO significando que ele já tenha sido pago, e sim apenas que houve a emissão. Este comportamento decorre da falta de ferramentas para tal verificação por parte do Banco do Brasil.
Parâmetros para transação via Banco do Brasil#
O lojista pode enviar os parâmetros do Banco do Brasil para gerar boletos via Carat.
Objeto additional_data#
No objeto JSON additional_data, os seguintes parâmetros podem ser enviados:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| discount_amount | Valor do desconto em centavos. Usado apenas para boletos. | < 12 N | NÃO |
| discount_limit_date | Data de vencimento do desconto no formato DDMMAAAA. Usado apenas para boletos. | 8 N | NÃO |
| duplicata_type | Informa o tipo de título que originará o boleto: DM - Duplicata Mercantil - utilizado quando forem vendidas mercadorias/produtos; DS - Duplicata de serviços - quando a loja virtual vender a prestação de serviços. | 2 A | SIM¹ |
- ¹ Obrigatório para boleto.
Objeto additiona_data.payer#
No Objeto additional_data.payer, os seguintes parâmetros podem ser enviados:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| name | Nome do comprador. | AN² | SIM |
| surname | Sobrenome do comprador. | AN² | SIM |
| address_street_name | Endereço do comprador. | AN³ | SIM |
| address_street_number | Número do endereço do comprador. | AN³ | SIM |
| address_street_complement | Complemento do endereço do comprador. | AN³ | SIM |
| address_zip_code | CEP do comprador | 8 N | SIM |
| city | Cidade do comprador | < 18 A | SIM |
| state | Estado (UF) do comprador | < 2 A | SIM |
| identification_number | Número do documento (CPF ou CNPJ) do comprador, sem formatação. | < 14 N | SIM¹ |
| identification_type | Indica que o campo identification_number enviado representa: 1 - pessoa física 2 - pessoa jurídica | 1 N | SIM¹ |
¹ Obrigatório para boleto.
² O tamanho dos campos name e surname somados não pode ser maior do que 59 caracteres. Conta-se um caractere de espaçamento entre os campos, para totalizar 60 caracteres.
³ O tamanho dos campos address_street_name, address_street_number e address_street_complement somados não pode ser maior do que 58 caracteres. Conta-se um caractere de espaçamento entre cada um dos campos, para totalizar 60 caracteres.
Observação: Tamanhos dos campos de acordo com a documentação fornecida pelo Banco do Brasil.
Fluxo de pagamento Banco do Brasil#
Após enviar os dados de criação da transação e escolher o meio de pagamento Banco do Brasil, o seguinte fluxo de telas será iniciado:
A figura abaixo apresenta a tela anterior ao redirecionamento do comprador.
A figura seguinte apresenta a tela no Banco do Brasil, onde é realizado o pagamento:
Reemissão de Boletos#
O Carat disponibiliza a reemissão de boletos Banco do Brasil. Para isto, basta o redirecionamento do comprador para a seguinte url:
https://{{url}}/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
(homologação)https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
(produção)
Sendo que o envio do parâmetro nit é obrigatório e deve ser referente a uma transação de pagamento com o status Processada (PRO) com a autorizadora Banco do Brasil.
Caso a transação de pagamento não esteja no estado esperado, é apresentada a seguinte tela:
O simples acesso a esta URL já permite a visualização direta do boleto reemitido com os mesmos dados da primeira emissão, como na figura abaixo:
Exemplo de requisição no Pagamento HTML#
URL de endpoint no ambiente de Homologação:
https://{{url}}/e-sitef/init.se
Exemplo do parâmetro “request” com os parâmetros da transação do Carat + dados do Banco do Brasil (additional_data) em formato JSON: