Integração via API - Alterações referentes ao cartão de crédito

Relacionamos abaixo as alterações realizadas em nossa API de integração referentes à nova funcionalidade de cartão de crédito:

Geração de cobranças
Geração de cobranças (Checkout transparente)
Status de pagamento

Geração de cobranças


No serviço de geração de cobrança, disponibilizamos um novo parâmetro de requisição (paymentTypes) para identificação dos tipos de pagamentos da cobrança a ser gerada. E, além disso, um novo parâmetro de resposta (checkoutUrl) que contém a URL da página de checkout da cobrança.

Método

A geração da cobrança é 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

Parâmetros adicionais

Parâmetro Descrição Obrigatório
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

Parâmetros adicionais de resposta

Parâmetro Descrição
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ê *
- checkoutUrl: Link da página de checkout da cobrança
- 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.

Exemplos de Resposta

Formato JSON - Sucesso

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

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> <checkoutUrl>https://boletofacil/checkout/64445428941953EE6C2A694C575E441C</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> <checkoutUrl>https://boletofacil/checkout/2BC8A9089E820ADACBF99F11B653053A</link> <payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber> </charge> </charges> </data> </result>

Geração de cobranças (Checkout transparente)


Na opção de checkout transparente, disponibilizada no serviço geração de cobrança via cartão de crédito, é possível realizar o pagamento da cobrança em tempo real, sendo necessário que sejam informados algums parâmetros adicionais e obrigatórios.

Método

A geração da cobrança é 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

Parâmetros adicionais

Parâmetro Descrição Obrigatório
paymentTypes Define os tipos de pagamento da cobrança. No caso do checkout transparente, sempre deverá ser informada a opção CREDIT_CARD
Formato: CREDIT_CARD
Sim
creditCardNumber Número do cartão de crédito
Formato: Número inteiro de até 20 posições
Sim
creditCardHolderName Nome do titular do cartão de crédito
Formato: Livre com até 80 caracteres
Sim
creditCardSecurityCode Código de segurança do cartão de crédito - CVV/CVC
Formato: Número inteiro de até 4 dígitos
Sim
creditCardExpirationMonth Mês de expiração do cartão de crédito
Formato: Número inteiro entre 1 e 12
Sim
creditCardExpirationYear Ano de expiração do cartão de crédito
Formato: Número inteiro
Sim

Parâmetros obrigatórios

Parâmetro Descrição Obrigatório
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
Sim
billingAddressStreet Nome da rua/logradouro do comprador
Formato: Livre com até 80 caracteres
Sim
billingAddressNumber Número da residência do comprador
Formato: Livre com até 30 caracteres
Sim
billingAddressComplement Complemento do endereço do comprador
Formato: Livre com até 30 caracteres
Sim
billingAddressCity Cidade comprador
Formato: Livre com até 60 caracteres
Sim
billingAddressState Estado do comprador
Formato: Nome do estado ou UF válida
Sim
billingAddressPostcode CEP do comprador
Formato: CEP válido com ou sem hífen
Sim

Parâmetros adicionais de resposta

Parâmetro Descrição
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ê*
- checkoutUrl: Link da página de checkout da cobrança
- payNumber: Linha digitável para pagamento online
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)

Exemplos de Resposta

Formato JSON - Sucesso

{ "success": true, "data": { "charges":[ { "code": 101, "dueDate": "19/02/2013", "link": "https://boletofacil/boleto?token=23:m:3454", "checkoutUrl": "https://boletofacil/checkout/64445428941953EE6C2A694C575E441C", "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" } ] } }

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> <checkoutUrl>https://boletofacil/checkout/64445428941953EE6C2A694C575E441C</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> </payment> </payments> </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 paramêtro 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 AUTHORIZED (Pagamento autorizado).


Outra observação importante é que a notificação da cobrança ocorrerá mais de uma vez. Especialmente nos casos dos pagamentos com cartão de crédito, onde a cobrança passará por um fluxo de status, enviando uma notificação inicial com status AUTHORIZED e, posteriormente, após o processamento e a confirmação do pagamento, será enviada uma notificação com o status CONFIRMED.


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

Em caso de dúvidas, entre em contato.

keyboard_arrow_up
3.18.106