A integração via API é a forma mais avançada que existe.
Mas para fazer esse tipo, você vai precisar de alguém que tenha conhecimentos de programação. :)
Í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
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 Privado
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, 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 |
[1] 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 (billingAddressComplement e billingAddressNeighborhood), que são sempre opcionais.
[1] Caso seja informado um endereço inválido ou faltando dados obrigatórios, a cobrança será gerada sem endereço, exceto para checkout transparente, onde será retornado um erro.
[2] Obrigatório na opção de checkout transparente.
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
- 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
billetDetails |
Detalhes do boleto gerado (caso a opção de pagamento via boleto bancário tenha sido incluída na requisição)
Objeto contendo os atributos:
- bankAccount: Agência e conta bancária do beneficiário do boleto (conta operacional do Boleto Fácil)
- ourNumber: Nosso número formatado do boleto, com o dígito verificador
- barcodeNumber: Representação numérica do código de barras do boleto
- portfolio: Carteira de cobrança do boleto no banco.
|
payment |
Detalhes do pagamento, este elemento é filho de payments
Objeto contendo os atributos:
- id: Identificador único do pagamento no Boleto Fácil
- amount: Valor pago
- date: Data do registro do pagamento na instituição financeira
- fee: Taxa sobre o pagamento, em Reais.
- type: Tipo de pagamento, podendo ser: BOLETO, CREDIT_CARD ou INSTALLMENT_CREDIT_CARD
- status: Situação do pagamento, podendo ser: AUTHORIZED, DECLINED, FAILED, NOT_AUTHORIZED ou CONFIRMED (ver mais detalhes)
- creditCardId: Identificação única do cartão de crédito
|
* Este elemento somente é retornado no caso de checkout transparente.
|
|
* 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,
"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>
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.
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.
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.
- O status das notificações de pagamento podem ser visualizados na aba de Cobranças, na opção Notificações de Pagamentos. Nesta tela também é possível reenviar notificações (tanto as falhadas como as bem-sucedidas), inclusive com a opção de alterar a URL de envio caso esta esteja incorreta.
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.
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.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
|
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,
"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>
Janela de consulta
- Será possível consultar dados de pagamentos até 30 dias após a data de confirmação.
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.
Consulta de pagamentos e cobranças
DESCRIÇÃO
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.
URL
https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges
LIMITE
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.
Exemplo de requisição
https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges?token=SEUTOKEN&beginPaymentDate=01/07/2017
Parâmetros
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 |
* É necessário informar ao menos uma data inicial (beginDueDate ou beginPaymentDate).
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ê *
- 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
|
* 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.
Exemplos de Resposta
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>
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 |
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 |
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>
Status de pagamento
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 |
* Alguns status foram omitidos para um melhor entendimento do fluxo de pagamento. Deve-se observar que o status que determina se uma cobrança está paga é o status CONFIRMED
Estorno de pagamento (cartão de crédito)
Descrição
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.
URL
https://www.boletobancario.com/boletofacil/integration/api/v1/refund-credit-card-payment
Parâmetros
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 |
Geração de hash do cartão de crédito
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:
Biblioteca de Criptografia
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>
Obtendo hash do cartão de crédito
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>
Funções auxiliares
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>
Tokenização do cartão de crédito
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.
URL
https://www.boletobancario.com/boletofacil/integration/api/v1/card-tokenization
Parâmetros
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.
Criptografia de Cartão de Crédito para Aplicativos Android
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.