Botão de pagamento

Cobrar diretamente em seu website requer apenas 2 passos:

1) Configure um botão de pagamento.

2) Copie o código HTML e cole em seu website.


Integração via API

A integração via API é a forma mais avançada de integração.
Conhecimentos de programação são fundamentais neste caso.


Índice:

Testes
Token
Geração de cobranças
Notificação de pagamentos
Simulação de pagamentos
Consulta de saldo
Solicitação de transferência
Cancelamento de cobrança
Plugins


Testes

Para testes utilize o ambiente Sandbox: https://sandbox.boletobancario.com/boletofacil

Neste ambiente você poderá simular pagamentos para testar o ciclo completo.

Este ambiente é totalmente separado do ambiente de produção, portanto você deve criar um novo cadastro nele.

Token

Para a integração será utilizado um token de identificação da sua conta.

Geração de cobranças

Método

A geração de boletos é feita através de requisições HTTPS, que podem utilizar tanto o método POST quanto o método GET.

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge

Charset

Todas as requisições feitas pelo seu sistema ao Boleto Fácil devem utilizar UTF-8. As respostas enviadas pelo Boleto Fácil também utilizam este mesmo charset.

Atenção

Antes de utilizar em produção, certifique-se de que o cadastro no Boleto Fácil esteja verificado para não haver problema com limites de emissão.

Parâmetros

Parâmetro Descrição Obrigatório
token O token do Favorecido, que pode ser gerado acima Sim
description Descrição sobre a que se refere o pagamento

Formato: Livre com até 400 caracteres - Até 4 linhas
Exemplos: Pedido 48192 / TV 40 Polegadas / Cosméticos
Sim
reference Código de referência da cobrança
Este código fica associado à(s) cobrança(s) criada(s) por esta requisição e é útil para vincular as transações do Boleto Fácil às vendas registradas no seu sistema

Formato: Livre com até 255 caracteres
Não
amount Valor do boleto ou da parcela no caso de cobrança parcelada

Formato: Decimal, separado por ponto. Maior ou igual a 2.30 e menor ou igual a 1000000.00
Sim
dueDate Data de vencimento do boleto ou da primeira parcela, no caso de cobrança parcelada
Para parcelamento as prestações terão vencimento com 1 mês de intervalo, a partir da data informada

Formato: dd/mm/aaaa
Valor padrão: Se não definido será 3 dias após a data de emissão
Não
installments Número de parcelas da cobrança
Se igual a 1, será gerado um boleto simples, se 2 ou mais, será gerado um carnê

Formato: Número inteiro maior ou igual a 1 e menor ou igual a 12
Valor padrão: 1
Não
maxOverdueDays Número máximo de dias que o boleto poderá ser pago após o vencimento
Zero significa que o boleto não poderá ser pago após o vencimento

Formato: Número inteiro maior ou igual a 0 e menor ou igual a 90
Valor padrão: 0
Não
fine Multa para pagamento após o vencimento
Só é efetivo se maxOverdueDays for maior que zero

Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor ou igual a 20.00 (2.00 é o valor máximo permitido por lei)
Valor padrão: 0.00
Não
interest Juros para pagamento após o vencimento
Só é efetivo se maxOverdueDays for maior que zero

Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor ou igual a 20.00 (1.00 é o valor máximo permitido por lei)
Valor padrão: 0.00
Não
discountAmount Valor do desconto
Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor que o valor da cobrança (amount)
Valor padrão: 0.00
Não
discountDays Dias concessão de desconto para pagamento antecipado. Exemplo: Até 10 dias antes do vencimento.
Formato: Número inteiro maior ou igual a -1
Valor padrão: -1
Atenção: Valor igual a 0 (zero) significa conceder desconto até a data do vencimento
Não
payerName Nome completo do comprador
Formato: Livre com até 60 caracteres
Sim
payerCpfCnpj CPF ou CNPJ do comprador
Formato: CPF ou CNPJ válido, aceito com ou sem pontuação
Sim
payerEmail Endereço de email do comprador
Formato: Endereço de email válido, com até 80 caracteres
Não
payerSecondaryEmail Endereço de email secundário do comprador
Formato: Endereço de email secundário válido, com até 80 caracteres
Não
payerPhone Telefone do comprador
Formato: Livre com até 25 caracteres
Não
payerBirthDate Data de nascimento do comprador
Formato: dd/mm/aaaa
Não
billingAddressStreet Nome da rua/logradouro do comprador
Formato: Livre com até 80 caracteres
Não*
billingAddressNumber Número da residência do comprador
Formato: Livre com até 30 caracteres
Não*
billingAddressComplement Complemento do endereço do comprador
Formato: Livre com até 30 caracteres
Não
billingAddressCity Cidade comprador
Formato: Livre com até 60 caracteres
Não*
billingAddressState Estado do comprador
Formato: Nome do estado ou UF válida
Não*
billingAddressPostcode CEP do comprador
Formato: CEP válido com ou sem hífen
Não*
notifyPayer Define se o Boleto Fácil enviará emails de notificação sobre esta cobrança para o comprador
O email com o boleto ou carnê só será enviado ao comprador se este parâmetro for igual a true e o endereço de email do comprador estiver presente
O lembrete de vencimento só será enviado se as condições acima forem verdadeiras e se na configuração do Favorecido os lembretes estiverem ativados

Formato: true ou false
Valor padrão: true
Não
notificationUrl Define uma URL de notificação para que o Boleto Fácil envie notificações ao seu sistema sempre que houver algum evento de pagamento desta cobrança.
Se preferir, você pode configurar uma URL de notificação para todas as suas cobranças no tópico Notificação de pagamentos.

Formato: Endereço de URL com até 255 caracteres
Não
responseType Define o tipo de resposta à esta requisição

Formato: JSON ou XML
Valor padrão: JSON
Não
feeSchemaToken Define o token de um esquema de taxas e comissionamento alternativo Não
splitRecipient Destinatário da divisão de receitas (split), caso os boletos sejam emitidos pelo "dono" do esquema de taxas e comissionamento (split invertido) Não
* Os dados do endereço do comprador são opcionais, porém se qualquer dos parâmetros for informado, os demais passam a ser obrigatórios, exceto complemento (billingAddressComplement), que é sempre opcional.

Exemplo de requisição

https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge?token=SEUTOKEN&description=Pedido1791&amount=12.75&payerName=Nome+Sobrenome&payerCpfCnpj=94648945123

Parâmetros de resposta

Parâmetro Descrição
success Indica se a requisição foi executada com sucesso ou não

Formato: true ou false
errorMessage Texto contendo a mensagem de erro, presente somente se success = false

Formato: Texto livre
data Dados da resposta, presente somente se success = true

Formato: Este elemento é apenas um container para charges
charges Lista das cobranças geradas, este elemento é filho de data

Formato: Array de charge
charge Detalhes da cobrança, este elemento é filho de charges

Objeto contendo os atributos:
- code: Código único de identificação da cobrança no Boleto Fácil
- dueDate: Data de vencimento do boleto ou parcela
- link: Link para visualização/download do boleto ou carnê *
- payNumber: Linha digitável para pagamento online
* Sempre que uma requisição gerar múltiplas cobranças (carnê), todas terão o mesmo link, pois apesar de cada parcela ser tratada individualmente no Boleto Fácil, apenas um documento é gerado. Você pode utilizar o link para redirecionar o comprador para a página do boleto ou carnet, ou, por exemplo, gravar o documento em seu sistema. Os links são permanentes, em nenhuma hipótese são excluídos, assim como as cobranças geradas.

Status da resposta

Além do parâmetro success, é recomendada a verificação do status HTTP para determinar se uma requisição foi executada com sucesso ou não.

Status Significado
200 Indica que a requisição foi executada com sucesso pelo Boleto Fácil
O corpo da resposta conterá o resultado, JSON ou XML conforme opção
400 Indica que a requisição não passou pelas validações do Boleto Fácil, portanto nenhuma cobrança foi emitida
O corpo da resposta conterá o resultado (mensagem de erro), JSON ou XML conforme opção
Qualquer outro status Indica que a requisição falhou por motivos alheios ao Boleto Fácil. Exemplos: Request Timeout, Request-URI Too Long, etc.
Nestes casos o corpo da resposta não conterá o resultado JSON ou XML, e sim uma mensagem produzida pelo servidor web, podendo ser vazio.

Exemplos de Resposta

Formato JSON - Sucesso

{ "success": true, "data": { "charges":[ { "code": 101, "dueDate": "19/02/2013", "link": "https://boletofacil/boleto?token=23:m:3454" "payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000" }, { "code": 102, "dueDate": "19/03/2013", "link": "https://boletofacil/boleto?token=23:m:3454" "payNumber": "03399.63290 64000.001024 00236.601027 3 67150000015000" } ] } }

Formato JSON - Erro

{ "success":false, "errorMessage":"Parâmetro 'payerName' não pode ter mais de 60 caracteres" }

Formato XML - Sucesso

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>true</success> <data> <charges> <charge> <code>101</code> <dueDate>19/02/2013</dueDate> <link>https://boletofacil/boleto?token=23:m:3454</link> <payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber> </charge> <charge> <code>102</code> <dueDate>19/03/2013</dueDate> <link>https://boletofacil/boleto?token=23:m:3454</link> <payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber> </charge> </charges> </data> </result>

Formato XML - Erro

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>false</success> <errorMessage>Valor mínimo para cobrança é de R$ 2,30</errorMessage> </result>

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>false</success> <errorMessage>Valor mínimo para cobrança é de R$ 2,30</errorMessage> </result>

Notificação de pagamentos

Você pode configurar o Boleto Fácil para enviar notificações para seu sistema sempre que houver um evento de pagamento.




Passo 1 - Notificação

O Boleto Fácil executa uma requisição POST na URL definida por você, informando o paymentToken para consulta das informações do pagamento.

Parâmetros da Notificação

Parâmetro Descrição
paymentToken Token que deverá ser utilizado pelo seu sistema para consultar os detalhes do pagamento no Boleto Fácil
chargeReference Código de referência da cobrança em seu sistema, informado no momento da emissão. Poderá, será vazio.
chargeCode Código único da cobrança no Boleto Fácil


- O Boleto Fácil utiliza o status HTTP retornado pelo seu sistema para confirmar que a notificação foi bem sucedida, status 200, ou mal sucedida, qualquer outro status. - Serão feitas até 50 tentativas de notificação com intervalos de 2 horas, tentativas extras poderão ser feitas no momento da confirmação. - As notificações de pagamento serão enviadas apenas para cobran¸as geradas via API de integração.

Atenção: Por questões de segurança esta primeira requisição não deve ser utilizada para para confirmar um pagamento em seu sistema. Para isso, utilize o Passo 2.

Passo 2 - Consulta

Seu sistema utiliza o paymentToken informado para consultar detalhes do pagamento


URL: https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-payment-details

Parametros de consulta

Parâmetro Descrição Obrigatório
paymentToken O token identificador do pagamento Sim
responseType Define o tipo de resposta à esta requisição

Formato: JSON ou XML
Valor padrão: JSON
Não

Parâmetros da Resposta

Parâmetro Descrição
success Indica se a requisição foi executada com sucesso ou não
Formato: true ou false
errorMessage Texto contendo a mensagem de erro, presente somente se success = false
Formato: Texto livre
data Dados da resposta, presente somente se success = true
Formato: Este elemento é apenas um container para payment
payment Dados do pagamento
Formato: Objeto
payment.id Identificador único do pagamento no Boleto Fácil
Formato: Número inteiro
payment.amount Valor pago
Formato: Decimal, separado por ponto
payment.date Data do registro do pagamento no banco
Formato: dd/mm/aaaa
payment.fee Taxa sobre o pagamento, em Reais.
Formato: Decimal, separado por ponto
payment.charge Dados da cobrança associada a este pagamento
Formato: Objeto
charge.code Código único da cobrança no Boleto Fácil
Formato: Número inteiro
charge.reference Código de referência da cobrança em seu sistema
Formato: Livre com até 255 caracteres
charge.amount Valor cobrado
Formato: Decimal, separado por ponto
charge.dueDate Data de vencimento do boleto
Formato: dd/mm/aaaa

Status da resposta

Além do parâmetro success, é recomendada a verificação do status HTTP para determinar se uma requisição foi executada com sucesso ou não.

Status Significado
200 Indica que a requisição foi executada com sucesso pelo Boleto Fácil
O corpo da resposta conterá o resultado, JSON ou XML conforme opção
400 Indica que a requisição não passou pelas validações do Boleto Fácil
O corpo da resposta conterá o resultado, JSON ou XML conforme opção
Qualquer outro status Indica que a requisição falhou por motivos alheios ao Boleto Fácil. Exemplos: Request Timeout, Request-URI Too Long, etc.
Nestes casos o corpo da resposta não conterá o resultado JSON ou XML, e sim uma mensagem produzida pelo servidor web, podendo ser vazio.

Exemplos de Resposta

Formato JSON - Sucesso

{ "success":true, "data":{ "payment":{ "id":32, "amount":95.00, "date":"19/02/2013", "fee":2.68, "charge":{ "amount":95.00, "code":101, "dueDate":"21/02/2013", "reference":"yourChargeRef5291" } } } }

Formato JSON - Erro

{ "success":false, "errorMessage":"Token inválido" }

Formato XML - Sucesso

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>true</success> <data> <payment> <id>32</id> <amount>95.00</amount> <date>19/02/2013</date> <fee>2.68</fee> <charge> <code>101</code> <reference>yourChargeRef5291</reference> <amount>95.00</amount> <dueDate>21/02/2013</dueDate> </charge> </payment> </data> </result>

Formato XML - Erro

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>false</success> <errorMessage>Token inválido</errorMessage> </result>

Pagamentos duplicados

- Apesar de pouco comum, é possível que um mesmo boleto seja pago múltiplas vezes. Recomendamos a utilização do id do pagamento para tratar estes casos.

- Por conta da possibilidade de pagamentos duplicados, notificações para cobranças com um pagamento já confirmado não devem ser ignoradas pelo seu sistema caso deseje fazer o tratamento automático.

- Opcionalmente você poderá tratar os pagamentos duplicados manualmente, o Boleto Fácil envia mensagens para o email de cadastro do favorecido com informações sobre cada pagamento duplicado.

Simulação de pagamentos

Esta opção permite testes do ciclo completo de cobrança/pagamento.


A simulação está disponível no ambiente Sandbox: https://sandbox.boletobancario.com/boletofacil

Você pode simular pagamentos diretamente na página de cobranças!




Consulta de Saldo

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-balance


Parâmetros

Parâmetro Descrição Obrigatório
token O token do Favorecido Sim
responseType Define o tipo de resposta à esta requisição

Formato: JSON ou XML
Valor padrão: JSON
Não

Exemplos de Resposta

Formato JSON

{ "success": true, "data": { "balance": 100 "withheldBalance": 30 "transferableBalance": 70 } }

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>true</success> <data> <balance>100.00</balance> <withheldBalance>30.00</withheldBalance> <transferableBalance>70.00</transferableBalance> </data> </result>

Solicitação de Transferência

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/request-transfer


Parâmetros

Parâmetro Descrição Obrigatório
token O token do Favorecido Sim
responseType Define o tipo de resposta à esta requisição

Formato: JSON ou XML
Valor padrão: JSON
Não

Exemplos de Resposta

Formato JSON

{ "success": true, "data": null }

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>true</success> <data/> </result>

Cancelamento de cobrança

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/cancel-charge


Parâmetros

Parâmetro Descrição Obrigatório
token O token do Favorecido Sim
code Código único de identificação da cobrança
Formato: Número inteiro
Sim
responseType Define o tipo de resposta à esta requisição
Formato: JSON ou XML
Valor padrão: JSON
Não

Exemplos de Resposta

Formato JSON

{ "success": true, "data": null }

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <result> <success>true</success> <data/> </result>

Em caso de dúvidas, entre em contato.

keyboard_arrow_up
3.10.0