O Boleto Fácil conta com diversos plugins que facilitam sua integração com diversos sistemas de e-commerce, sistemas de gerenciamento de provedores de Internet e outros. Para conferir a lista completa dos plugins disponíveis, clique aqui.
Além disso, há SDKs desenvolvidos para as seguintes plataformas de desenvolvimento de software:
1) Java
2) .NET
Índice:
• Testes
• Token
• Geração de cobranças
• Notificação de pagamentos
• Consulta de pagamentos e cobranças
• Simulação de pagamentos
• Consulta de saldo
• Solicitação de transferência
• Cancelamento de cobrança
• Status de pagamento
• Estorno de pagamento (cartão de crédito)
• Geração de hash do cartão de crédito
• Tokenização do cartão de crédito
• Criptografia de Cartão de Crédito para Aplicativos Android
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.
Para a integração será utilizado um token de identificação da sua conta.
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.
https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge
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.
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â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, com 2 casas decimais, separado por ponto. Maior ou igual a 2.30 e menor ou igual a 1000000.00 Atenção: Caso seja passado um valor com mais de 2 casas decimais, ele será TRUNCADO. Ex.: 2.419 -> 2.41 |
Sim |
| totalAmount |
Valor total da cobrança em caso de cobrança parcelada Formato: Decimal, com 2 casas decimais, separado por ponto. Maior ou igual a 2.30 e menor ou igual a 1000000.00 Observações: Caso o campo seja informado, o parâmetro installments passa a ser obrigatório, e o campo amount não deve ser informado. Atenção: Caso seja passado um valor com mais de 2 casas decimais, ele será TRUNCADO. Ex.: 2.419 -> 2.41. A diferença de centavos obtida a partir da divisão de parcelas, será lançada na primeira parcela. Ex.: R$ 10,00 em 3x(sem juros). A 1ª parcela será de R$ 3,34 e as demais serão de R$ 3,33. |
Não |
| 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 24 Cartão de Crédito: Se for oferecida a opção de pagamento com cartão de crédito, o número máximo de parcelas será 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 29 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 |
Juro mensal 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é 80 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é 100 caracteres |
Não [1, 2] |
| billingAddressNumber |
Número da residência do comprador Formato: Livre com até 30 caracteres |
Não [1, 2] |
| billingAddressComplement |
Complemento do endereço do comprador Formato: Livre com até 50 caracteres |
Não |
| billingAddressNeighborhood |
Bairro do endereço do comprador Formato: Livre com até 50 caracteres |
Não |
| billingAddressCity |
Cidade comprador Formato: Livre com até 60 caracteres |
Não [1, 2] |
| billingAddressState |
Estado do comprador Formato: Nome do estado ou UF válida |
Não [1, 2] |
| billingAddressPostcode |
CEP do comprador Formato: CEP válido com ou sem hífen |
Não [1, 2] |
| 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. Se houver uma URL global e uma na cobrança, será utilizada a que foi definida na cobrança. 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 |
| paymentTypes |
Define o(s) tipo(s) de pagamento da cobrança Formato: BOLETO e/ou CREDIT_CARD Valor padrão: BOLETO Exemplo: BOLETO,CREDIT_CARD |
Não [2] |
| creditCardHash |
Hash referente aos dados criptografados do cartão de crédito Formato: Hash do cartão de crédito, para mais detalhes acesse: Como gerar o hash de cartão de crédito |
Não [2] |
| creditCardStore |
Define se os dados do cartão de crédito serão armazenados. Se definido como true, será retornado uma identificação única do cartão de crédito (creditCardId) que poderá ser utilizado para pagamentos futuros. Formato: true ou false Valor padrão: false |
Não |
| creditCardId |
Identificação única do cartão de crédito previamente armazenado Formato: Código de identificação do cartão de crédito |
Não |
| paymentAdvance |
Define se o pagamento via cartão de crédito será antecipado Formato: true ou false Valor padrão: false |
Não |
https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge?token=SEUTOKEN&description=Pedido1791&amount=12.75&payerName=Nome+Sobrenome&payerCpfCnpj=94648945123
| 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 - reference: Código de referência da cobrança - dueDate: Data de vencimento do boleto ou parcela - link: Link para visualização/download do boleto ou carnê * - checkoutUrl: Link da página de checkout da cobrança - installmentLink: Link para visualização/download do boleto (somente a parcela) - payNumber: Linha digitável para pagamento online
|
||||||
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. |
Formato JSON - Sucesso
{
"success": true,
"data": {
"charges":[
{
"code": 101,
"reference": "ec2rda-cvdf2",
"dueDate": "19/02/2013",
"link": "https://boletofacil/boleto?token=23:m:3454",
"checkoutUrl": "https://boletofacil/checkout/64445428941953EE6C2A694C575E441C",
"installmentLink": "https://boletofacil/boleto?token=101:SD3G44G",
"payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000",
"billetDetails": {
"bankAccount": "3415-0 / 6948189",
"ourNumber": "000010000101 5",
"barcodeNumber": "03399746600000123459694818900001012126900102",
"portfolio": "COB. SIMPLES CSR"
}
},
{
"code": 102,
"reference": "tfv7e2-35jhk",
"dueDate": "19/03/2013",
"link": "https://boletofacil/boleto?token=23:m:3454",
"checkoutUrl": "https://boletofacil/checkout/2BC8A9089E820ADACBF99F11B653053A",
"installmentLink": "https://boletofacil/boleto?token=102:SD3G32",
"payNumber": "03399.63290 64000.001024 00236.601027 3 67150000015000",
"billetDetails": {
"bankAccount": "3415-0 / 6948189",
"ourNumber": "000010000102 9",
"barcodeNumber": "03399746600000123459694818900001012126900102",
"portfolio": "COB. SIMPLES CSR"
}
}
]
}
}
Formato JSON - Sucesso para Checkout Transparente
{
"success": true,
"data": {
"charges":[
{
"code": 101,
"reference": "ec2rda-cvdf2",
"dueDate": "19/02/2013",
"link": "https://boletofacil/boleto?token=23:m:3454",
"checkoutUrl": "https://boletofacil/checkout/64445428941953EE6C2A694C575E441C",
"installmentLink": "https://boletofacil/boleto?token=101:SD3G44G",
"payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000"
}
],
"payments":[
{
"id": 1113122,
"amount": "1141.4",
"date": "19/07/2017",
"fee": "27.8",
"type": "CREDIT_CARD",
"status": "AUTHORIZED"
"creditCardId": "XPTO-34H3F5"
}
]
}
}
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>
<reference>ec2rda-cvdf2</reference>
<dueDate>19/02/2013</dueDate>
<link>https://boletofacil/boleto?token=23:m:3454</link>
<checkoutUrl>https://boletofacil/checkout/64445428941953EE6C2A694C575E441C</link>
<installmentLink>https://boletofacil/boleto?token=101:SD3G44G</link>
<payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber>
<billetDetails>
<bankAccount>3415-0 / 6948189</bankAccount>
<ourNumber>000010000101 5</ourNumber>
<barcodeNumber>03399746600000123459694818900001012126900102</barcodeNumber>
<portfolio>COB. SIMPLES CSR</portfolio>
</billetDetails>
</charge>
<charge>
<code>102</code>
<reference>tfv7e2-35jhk</reference>
<dueDate>19/03/2013</dueDate>
<link>https://boletofacil/boleto?token=23:m:3454</link>
<checkoutUrl>https://boletofacil/checkout/2BC8A9089E820ADACBF99F11B653053A</link>
<installmentLink>https://boletofacil/boleto?token=102:SD3G32</link>
<payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber>
<billetDetails>
<bankAccount>3415-0 / 6948189</bankAccount>
<ourNumber>000010000102 9</ourNumber>
<barcodeNumber>03399746600000123459694818900001012126900102</barcodeNumber>
<portfolio>COB. SIMPLES CSR</portfolio>
</billetDetails>
</charge>
</charges>
</data>
</result>
Formato XML - Sucesso para Checkout Transparente
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
<success>true</success>
<data>
<charges>
<charge>
<code>101</code>
<reference>ec2rda-cvdf2</reference>
<dueDate>19/02/2013</dueDate>
<link>https://boletofacil/boleto?token=23:m:3454</link>
<checkoutUrl>https://boletofacil/checkout/64445428941953EE6C2A694C575E441C</link>
<installmentLink>https://boletofacil/boleto?token=101:SD3G44G</link>
<payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber>
</charge>
</charges>
<payments>
<payment>
<id>1113123</id>
<amount>163.90</amount>
<date>19/07/2017</date>
<fee>4.34</fee>
<type>CREDIT_CARD</type>
<status>AUTHORIZED</status>
<creditCardId>XPTO-34H3F5</status>
</payment>
</payments>
</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>
Você pode configurar o Boleto Fácil para enviar notificações para seu sistema sempre que houver um evento de pagamento.
Alternativamente pode ser utilizado o parâmetro notificationUrl na geração da cobrança.
Se for definida uma URL global (esta), e uma na cobrança (parâmetro notificationUrl), será utilizada a que foi definida na cobrança.
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â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 |
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.
Atenção: O sistema não garante unicidade de notificações, utilize sempre o ID do pagamento na consulta (passo 2) para verificar se o seu sistema já recebeu determinada notificação.
Seu sistema utiliza o paymentToken informado para consultar detalhes do pagamento
URL: https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-payment-details
| 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â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.type | Tipo de pagamento, podendo ser: BOLETO, CREDIT_CARD ou INSTALLMENT_CREDIT_CARD |
| payment.status | Situação do pagamento, podendo ser: AUTHORIZED, DECLINED, FAILED, NOT_AUTHORIZED ou CONFIRMED (ver mais detalhes) |
| payment.creditCardId | Identificação única do cartão de crédito |
| 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 |
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. |
Formato JSON - Sucesso
{
"success":true,
"data":{
"payment":{
"id":32,
"amount":95.00,
"date":"19/02/2013",
"fee":2.68,
"type":"CREDIT_CARD",
"status":"AUTHORIZED",
"creditCardId":"XPTO-34H3F5",
"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>
<type>CREDIT_CARD</fee>
<status>AUTHORIZED</fee>
<creditCardId>XPTO-34H3F5</creditCardId>
<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>
- Será possível consultar dados de pagamentos até 30 dias após a data de confirmação.
- 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.
Caso seu sistema não possua uma URL para callback para receber as notificações de pagamento, este método pode ser utilizado para consultar ativamente pagamentos e cobranças.
Somente cobranças com pagamentos serão listadas.
https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges
No ambiente de produção há um limite de 3 consultas diárias por cadastro, uma vez atingido este limite as consultas subseqüentes falharão com uma mensagem de erro apropriada.
https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges?token=SEUTOKEN&beginPaymentDate=01/07/2017
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| token | O token do Favorecido | Sim |
| beginDueDate |
Data de Vencimento - a partir de Formato: dd/mm/aaaa |
Não* |
| endDueDate |
Data de Vencimento - até Formato: dd/mm/aaaa |
Não |
| beginPaymentDate |
Data de Pagamento - a partir de Formato: dd/mm/aaaa |
Não* |
| endPaymentDate |
Data de Pagamento - até Formato: dd/mm/aaaa |
Não |
| responseType |
Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON |
Não |
| 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ê * - installmentLink: Link para visualização/download do boleto (somente a parcela) - payNumber: Linha digitável para pagamento online |
| payments |
Lista dos pagamentos efetuados para esta cobrança, este elemento é filho de data Formato: Array de payment |
| payment |
Detalhes do pagamento efetuado, este elemento é filho de payments Objeto contendo os atributos: - id: Código único de identificação do pagamento no Boleto Fácil - amount: O valor do pagamento efetuado - date: Data do pagamento efetuado - fee: Taxa sobre o pagamento, em Reais - type: Tipo de pagamento - status: Status do pagamento |
Formato JSON - Sucesso
{
"success": true,
"data": {
"charges":[
{
"code": 101,
"dueDate": "19/02/2013",
"link": "https://boletofacil/boleto?token=23:m:3454",
"installmentLink": "https://boletofacil/boleto?token=101:HGJD3454",
"payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000",
"payments": [
{
"id": 1113123,
"amount": 163.9,
"date": "19/07/2017",
"fee": 4.34,
"type": "BOLETO",
"status": "CONFIRMED"
}
]
},
{
"code": 102,
"dueDate": "19/03/2013",
"link": "https://boletofacil/boleto?token=23:m:3454",
"installmentLink": "https://boletofacil/boleto?token=102:ERT5447"
"payNumber": "03399.63290 64000.001024 00236.601027 3 67150000015000",
"payments": [
{
"id": 1113122,
"amount": 1141.4,
"date": "19/07/2017",
"fee": 27.8,
"type": "BOLETO",
"status": "CONFIRMED"
}
]
}
]
}
}
Formato JSON - Erro
{
"success":false,
"errorMessage":"A data de início de pagamento não pode ser menor que 5 dias a partir do dia de hoje"
}
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>
<installmentLink>https://boletofacil/boleto?token=101:HGJD3454</link>
<payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber>
<payments>
<payment>
<id>1113123</id>
<amount>163.90</amount>
<date>19/07/2017</date>
<fee>4.34</fee>
<type>BOLETO</type>
<status>CONFIRMED</status>
</payment>
</payments>
</charge>
<charge>
<code>102</code>
<dueDate>19/03/2013</dueDate>
<link>https://boletofacil/boleto?token=23:m:3454</link>
<installmentLink>https://boletofacil/boleto?token=102:ERT5447</link>
<payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber>
<payments>
<payment>
<id>1113122</id>
<amount>1141.40</amount>
<date>19/07/2017</date>
<fee>27.80</fee>
<type>BOLETO</type>
<status>CONFIRMED</status>
</payment>
</payments>
</charge>
</charges>
</data>
</result>
Formato XML - Erro
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
<success>false</success>
<errorMessage>A data de início de pagamento não pode ser menor que 5 dias a partir do dia de hoje</errorMessage>
</result>
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!
https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-balance
| 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 |
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>
https://www.boletobancario.com/boletofacil/integration/api/v1/request-transfer
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| token | O token do Favorecido | Sim |
| amount |
Valor a ser transferido Formato: Decimal, separado por ponto. Valor padrão: Saldo total disponível |
Não |
| responseType |
Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON |
Não |
Formato JSON
{
"success": true,
"data": null
}
Formato XML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
<success>true</success>
<data/>
</result>
https://www.boletobancario.com/boletofacil/integration/api/v1/cancel-charge
| 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 |
Formato JSON
{
"success": true,
"data": null
}
Formato XML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
<success>true</success>
<data/>
</result>
Os serviços que retornam informações dos pagamentos como os de geração de cobrança (checkout transparente), notificação de pagamentos e de consulta de pagamentos, possuem um parâmetro de retorno adicional chamado status, que refere-se ao status do pagamento.
Uma cobrança poderá ter várias ocorrências de pagamentos, por exemplo, uma ocorrência com status FAILED (Pagamento não realizado) e uma ocorrência com status CONFIRMED (Pagamento confirmado).
Abaixo estão relacionados os principais status do pagamento e a descrição dos mesmo*:
| Status | Descrição |
|---|---|
| AUTHORIZED | Pagamento autorizado (Aguardando confirmação) |
| DECLINED | Pagamento rejeitado pela análise de risco. |
| FAILED | Pagamento não realizado |
| NOT_AUTHORIZED | Pagamento não autorizado pela instituição responsável pelo cartão de crédito |
| CONFIRMED | Pagamento confirmado |
Cobranças pagas com cartão de crédito podem ser estornadas via API.
Esse procedimento estornará integralmente ou parcialmente o valor da compra para o cliente que efetuou o pagamento da cobrança. Caso seja uma cobrança parcelada, todas as parcelas serão estornadas.
https://www.boletobancario.com/boletofacil/integration/api/v1/refund-credit-card-payment
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| token | O token do Favorecido | Sim |
| id | ID do pagamento retornado pela plataforma Boleto Fácil | Sim |
| amount | Valor a ser estornado. Caso não informado, o estorno será total. Caso informado um valor menor que o valor total da transação, o estorno será parcial e cada parcela terá seu valor reduzido. | Não |
Visando garantir a segurança das transações realizadas em nossa plataforma, a nossa API adota uma política de criptografia dos dados de cartão de crédito de ponta-a-ponta.
Por conta disso, as aplicações clientes (browser, apps e etc) que estiverem capturando dados sensíveis de cartão de crédito, deverão seguir as etapas abaixo para trafegarem dados de cartão de crédito em nosso ambiente:
A próxima etapa será a inclusão da nossa biblioteca Javascript (client-side) em seu código.
Esta biblioteca está disponível no seguinte endereço:
<script type="text/javascript" src="https://www.boletobancario.com/boletofacil/wro/direct-checkout.min.js"></script>
A última etapa desse processo será a obtenção do hash do cartão de crédito.
Nesta etapa você precisará informar os dados do cartão de crédito para a nossa biblioteca, que irá validar dados do cartão de crédito, criptografá-los e retornar um hash.
Detalhamos a seguir um exemplo de utilização de nossa biblioteca de como obter o hash do cartão de crédito:
<script type="text/javascript">
var checkout = new DirectCheckout('SEU TOKEN PUBLICO'); /* Em sandbox utilizar o construtor new DirectCheckout('SEU TOKEN PUBLICO', false); */
var cardData = {
cardNumber: '0000000000000000',
holderName: 'Nome do Titular do Cartão',
securityCode: '000',
expirationMonth: '12',
expirationYear: '2045'
};
checkout.getCardHash(cardData, function(cardHash) {
/* Sucesso - A variável cardHash conterá o hash do cartão de crédito */
}, function(error) {
/* Erro - A variável error conterá o erro ocorrido ao obter o hash */
});
</script>
A biblioteca disponibilizada também possui uma série de métodos auxiliares para a validação de dados do cartão de crédito, conforme demonstrado a seguir:
<script type="text/javascript">
var checkout = new DirectCheckout('SEU TOKEN PUBLICO'); /* Em sandbox utilizar o construtor new DirectCheckout('SEU TOKEN PUBLICO', false); */
var cardData = {
cardNumber: '0000000000000000',
holderName: 'Nome do Titular do Cartão',
securityCode: '000',
expirationMonth: '12',
expirationYear: '2045'
};
/* isValidSecurityCode: Valida número do cartão de crédito (retorna true se for válido) */
checkout.isValidCardNumber(cardData.cardNumber);
/* isValidSecurityCode: Valida código de segurança do cartão de crédito (retorna true se for válido) */
checkout.isValidSecurityCode(cardData.cardNumber, cardData.securityCode);
/* isValidExpireDate: Valida data de expiração do cartão de crédito (retorna true se for válido) */
checkout.isValidExpireDate(cardData.expirationMonth, cardData.expirationYear);
/* isValidCardData: Validação dos dados do cartão de crédito(retorna true se for válido) */
checkout.isValidCardData(cardData, function(error) {
/* Erro - A variável error conterá o erro ocorrido durante a validação dos dados do cartão de crédito */
});
/* getCardType: Obtem o tipo de cartão de crédito (bandeira) */
checkout.getCardType(cardData.cardNumber);
</script>
Para facilitar o processo de geração de cobranças recorrentes, nossa API provê a funcionalidade de tokenização dos dados do cartão de crédito de seu cliente.
Nesse processo você deverá utilizar a biblioteca de criptografia listada acima para que a transação de tokenização seja feita de forma segura. Esse processo pode ser feito no momento da compra ou em uma transação exclusiva para tokenização do cartão.
A transação será feita em duas etapas:
1) Você deve obter o hash do cartão utilizando a biblioteca de criptografia conforme instruções acima. (client-side).
2) Com o hash gerado pela biblioteca de criptografia, você deverá enviar para o seu servidor essa informação e efetuar uma chamada server-side para o endereço conforme instruções da tabela abaixo.
https://www.boletobancario.com/boletofacil/integration/api/v1/card-tokenization
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| token | O token do Favorecido | Sim |
| creditCardHash | Hash do cartão gerado pela biblioteca de criptografia | Sim |
Caso o cartão seja válido, retornaremos para você o creditCardId. Essa informação poderá ser utilizada no momento da geração de cobranças.
Abaixo temos um diagrama de funcionamento do processo de tokenização. Dependendo da bandeira do cartão do seu cliente, será feito uma transação de R$ 0,50 e o estorno logo na sequência. Na maioria dos casos, não será exibido nenhum valor na fatura do seu cliente.
Para os desenvolvedores mobile, a Juno criou uma biblioteca javascript de captura dos dados de cartão de crédito para Android, permitindo que você crie um checkout transparente usando nossa solução e possa tokenizar o método de pagamento do seu cliente via aplicativo, sem precisar implementar um recurso de webview.
A documentação está disponível no Github da Juno.
Como você vai precisar de permissão da Juno para adicionar esta feature no seu checkout, não esquece de entrar em contato com a gente.
Em caso de dúvidas, entre em contato.