As transações online via cartão de crédito exigem apenas a numeração de face e o código no verso do cartão, o que pode resultar em transações suspeitas. Por isso, é importante adotar procedimentos de segurança para evitar prejuízos financeiros, como o Chargeback.
Quando uma transação com cartão de crédito é realizada, ela passa por três etapas: autorização da operadora, análise de segurança e captura. Cada transação é analisada para identificar possíveis riscos. Se for aprovada, o valor é debitado na fatura do cliente. Caso contrário, o valor fica reservado até que a comunicação reversa seja concluída e o limite do cartão seja reestabelecido.
Confira a lista de cartões de crédito aceitos pela Efí
Visa
Master
AmericanExpress
Elo
Atenção!
Para fazer o pagamento com cartão de crédito,é necessário obter o payment_token da transação. Portanto, é imprescindível seguir os procedimentos para obter o payment_token conforme descrito no documento antes de criar a cobrança com cartão de crédito.
Outra informação importante é você precisa cadastrar o ramo de atividade em sua conta. Confira mais detalhes aqui.
Atenção!
Para utilização e reanalise de limite de emissão de cobranças por cartão de crédito, através de integração por checkout transparente ou link de pagamento (cartão não presente), é necessário preenchimento do formulário abaixo.
Após o preenchimento do formulário, nossa equipe poderá levar até 5 dias utéis para análise.
Um payment_token é um conjunto de caracteres gerado pela API Efí, que representa os dados do cartão da pessoa pagadora. Ele pode ser configurado para uso único ou reutilização recorrente.
Para transações com cartão de crédito, é realizada uma etapa prévia à criação da cobrança, onde ocorre a geração do payment_token. Isso pode ser feito transmitindo os dados do cartão, podendo utilizar a biblioteca JavaScript, ou o módulo jQuery.
Tokenização de cartão
Se você precisa reutilizar o payment_token para fins de recorrência, utilize o atributo reuse com o valor booleano true. Dessa forma, o payment_token pode ser usado em mais de uma transação de forma segura, sem a necessidade de salvar os dados do cartão
Simulação em Ambiente de Homologação
Para os fluxos One Step e Two Steps sem autenticação 3DS, a simulação de cobranças de cartão em ambiente de homologação considera o último dígito do número do cartão utilizado:
Cartão com final 1 retorna: "reason":"Dados do cartão inválidos."
Cartão com final 2 retorna: "reason":"Transação não autorizada por motivos de segurança."
Cartão com final 3 retorna: "reason":"Transação não autorizada, tente novamente mais tarde."
Demais finais têm transação aprovada.
Para cobranças com autenticação 3DS criadas pelo endpoint POST /v1/charge/card, o cartão com final 0 simula a apresentação do desafio. Consulte os demais cenários em Homologação e cenários de teste.
Esta biblioteca JavaScript permite a criptografia dos dados do cartão diretamente no navegador do cliente, gerando o payment_token, identificando a bandeira do cartão e obtendo informações de parcelamento.
Abaixo, fornecemos algumas opções de instalação da biblioteca para atender a projetos web que utilizam JavaScript puro ou frameworks modernos. Veja os detalhes a seguir:
Para aplicações que não possuem DOM nativo, como React Native, Ionic, Swift, e outros frameworks similares, é necessário utilizar um componente WebView para executar a biblioteca. O WebView permite que a biblioteca funcione corretamente, pois fornece um ambiente DOM para sua execução. Disponibilizamos aqui um exemplo de demonstração com React Native.
Se você estiver utilizando TypeScript, quando você instalar a biblioteca payment-token-efi, o TypeScript deve ser capaz de encontrar os tipos automaticamente localizados em types/payment-token-efi.d.ts
Para utilizar esse script, é necessário fornecer o código Identificador de conta (payee_code) como parâmetro para gerar o payment_token dos dados do cartão de crédito. Você pode obter essa informação em sua conta digital, no menu API > Introdução > Identificador de conta. Veja onde encontrá-lo. Certifique-se de ter essa informação disponível ao utilizar as funções do script.
A função isScriptBlocked() verifica se o script de fingerprint, que ajuda a manter a segurança da transação ao coletar informações do pagador, está sendo bloqueado por alguma extensão ou configuração do navegador. A recomendação é executar essa função logo que a página de checkout carregar, assim é possível já identificar se houve bloqueio antes do cliente tentar fazer o pagamento.
Requisição
Código
asyncfunctioncheckScriptBlocking(){ const isBlocked =awaitEfiPay.CreditCard.isScriptBlocked(); if(isBlocked){ console.log("O script está bloqueado!"); }else{ console.log("O script não está bloqueado."); } }
Respostas
A resposta abaixo representa as possíveis saídas do consumo.
🟢 200
"true" se o script de fingerprint estiver bloqueado, ou "false" caso contrário.
asyncfunctiongeneratePaymentToken(){ try{ const result =awaitEfiPay.CreditCard .setAccount("Identificador_de_conta_aqui") .setEnvironment("production")// 'production' or 'sandbox' .setCreditCardData({ brand:"visa", number:"4485785674290087", cvv:"123", expirationMonth:"05", expirationYear:"2029", holderName:"Gorbadoc Oldbuck", holderDocument:"94271564656", reuse:false, enable3ds:true,//opcional: habilita a autenticação 3DS Secure totalValue:28990,// obrigatório quando o enable3ds for true (valor em centavos) }) .getPaymentToken(); const payment_token = result.payment_token; const card_mask = result.card_mask; const tds_identifier = result.tds_identifier;// disponível quando enable3ds for true console.log("payment_token", payment_token); console.log("card_mask", card_mask); console.log("tds_identifier", tds_identifier); }catch(error){ console.log("Código: ", error.code); console.log("Nome: ", error.error); console.log("Mensagem: ", error.error_description); } }
Respostas
A resposta abaixo representa Sucesso do consumo.
🟢 200
{ "payment_token":"47f13d72c883c1547ae4a0df11eb46194f333f85", "card_mask":"XXXXXXXXXXXX3991", "tds_identifier":"f81d4fae-7dec-11d0-a765-00a0c91e6bf6"//retornado quando enable3ds for true }
O debugger pode ser ativado para depurar e encontrar possível falhas.
Requisição
Código
EfiPay.CreditCard.debugger(true);
Respostas
Em caso de erro, será retornado no try/catch o objeto como apresentado abaixo.
🔴 400
{ "code":3500056, "error":"invalid_brand", "error_description":"O parâmetro [brand] informado é inválido. As opções válidas são: 'visa', 'mastercard', 'amex', 'diners' ou 'elo'." }
f) Obter o identificador 3DS (reutilizando um payment_token existente)
Obter o identificador 3DS
Função para inicializar o processo de autenticação 3DS Secure e obter um novo tds_identifier sem precisar informar os dados do cartão novamente. Utilize este método nos casos em que o payment_token já foi gerado anteriormente, como por exemplo, ao reutilizar um cartão salvo, e você precisa iniciar uma nova verificação 3DS para uma nova transação, passando apenas o payment_token existente e o valor da nova cobrança.
Requisição
Código
asyncfunctionget3dsIdentifier(){ try{ const result =awaitEfiPay.CreditCard .setAccount("Identificador_de_conta_aqui") .setEnvironment("production")// 'production' ou 'sandbox' .get3dsIdentifier( "payment_token_aqui",// payment_token gerado anteriormente 28990// valor total da nova cobrança em centavos ); console.log("tds_identifier", result.tds_identifier); }catch(error){ console.log("Código:", error.code); console.log("Nome:", error.error); console.log("Mensagem:", error.error_description); } }
Uma opção para gerar o payment_token a partir dos dados do cartão é usar o front-end. Para isso, você precisa de um código JavaScript específico da sua conta Efí. Para gerá-lo, siga estes passos:
Após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos. Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Este script permitirá executar duas funções:
getPaymentToken: Gera o payment_token de acordo com os dados do cartão;
Obtendo um "payment_token" (getPaymentToken) e informações sobre parcelamentos (getInstallments)
Código
$gn.ready(function(checkout){ checkout.getPaymentToken( { brand:'visa',// bandeira do cartão number:'4012001038443335',// número do cartão cvv:'123',// código de segurança expiration_month:'05',// mês de vencimento expiration_year:'2021',// ano de vencimento reuse:false// tokenização/reutilização do payment_token }, function(error, response){ if(error){ // Trata o erro ocorrido console.error(error); }else{ // Trata a resposta console.log(response); } } ); checkout.getInstallments( 50000,// valor total da cobrança 'visa',// bandeira do cartão function(error, response){ if(error){ // Trata o erro ocorrido console.log(error); }else{ // Trata a respostae console.log(response); } } ); });
Atributos relacionados ao envio de dados do cartão e retorno das funcões
$gn.ready (checkout)
Essa função de inicialização permite a chamada das funções getPaymentToken e getInstallments. Você passa um objeto (checkout) que recebe as instâncias dessas funções.
getPaymentToken
Função para gerar o payment_token
Respostas
As respostas abaixo representam Sucesso e falha do consumo.
{ "code":3500056, "error":"invalid_brand", "error_description":"O parâmetro [brand] informado é inválido. As opções válidas são: 'visa', 'mastercard', 'amex', 'diners' ou 'elo'." } Ou { "code":3500053, "error":"missing_total", "error_description":"O parâmetro [total] é obrigatório e deve ser um inteiro." } Ou { "code":3500006, "error":"greater_than_limit", "error_description":"O total fornecido é superior ao limite máximo por transação." }
O procedimento de geração do payment_token no back-end foi descontinuado com base em medidas de segurança. A fim de garantir a proteção dos dados, informações sensíveis e evitar recusa nas transações de cartão de crédito, recomendamos que você descontinue o uso deste serviço . Com base em nossa avaliação, gostaríamos de sugerir a geração através do front-end da aplicação
Criação de cobrança por cartão de crédito com autenticação 3DS
Atenção!
Para utilizar o reuse do payment_token em cobranças recorrentes na modalidade de assinatura (sem a presença do pagador na tela), é necessário utilizar o endpoint específico de assinatura do Efí.
Importante!
A rota antiga de pagamento será descontinuada em breve. Por isso, recomendamos que novas integrações sejam realizadas utilizando a rota POST /v1/charge/card, considerando as limitações informadas acima.
A data de descontinuação será comunicada previamente.
A autenticação 3DS permite que o banco emissor solicite uma verificação adicional da identidade da pessoa pagadora durante uma compra com cartão de crédito.
Para criar uma cobrança com autenticação 3DS, obtenha o payment_token e o tds_identifier pela biblioteca JavaScript. Na geração do token, informe enable3ds como true e o valor total da cobrança, em centavos, no campo totalValue.
Caso utilize um token existente, obtenha um novo identificador pelo método get3dsIdentifier. Esse procedimento também exige a presença do pagador para realizar a autenticação 3DS, quando necessária, e não habilita cobranças recorrentes sem sua participação.
Em seguida, seu servidor deverá enviar uma requisição POST para a rota /v1/charge/card, informando os itens da compra, os dados do cliente e os dados de autenticação.
Neste endpoint, os atributos customer, payment_token e installments são enviados diretamente na raiz da requisição. O objeto obrigatório tds_info deve conter tds_identifier e challenge_callback_url.
A cobrança poderá retornar com aprovação ou recusa imediata, sem apresentar um desafio à pessoa pagadora. Quando houver necessidade de autenticação adicional, a API retornará o status waiting e o objeto tds_challenge, com os dados necessários para apresentar o desafio no front-end.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
Requer ativação da API de Emissão de cobranças em sua aplicação.
Requisição
Dados de entrada
{ "items":[ { "name":"Meu Produto", "value":10000, "amount":1 } ], "customer":{ "name":"Gorbadoc Oldbuck", "cpf":"94271564656", "email":"[email protected]", "phone_number":"5144916523" }, "installments":1, "payment_token":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b1",// Token obtido via tokenização no front-end. "tds_info":{ "tds_identifier":"f81d4fae-7dec-11d0-a765-00a0c91e6bf6",// Identificador único para a transação 3DS no formato UUID obtido no front-end. "challenge_callback_url":"https://meusite.com.br/3ds/callback"// URL da sua aplicação para a qual o cliente será redirecionado após completar o desafio 3DS. } }
Respostas
As respostas abaixo representam os possíveis retornos HTTP 200 do consumo.
O objeto tds_challenge é retornado quando há desafio 3DS. O status waiting também pode indicar processamento, sem esse objeto. O conteúdo de html_template está simplificado neste exemplo; utilize o HTML completo retornado pela API.
Respostas de erro
As respostas abaixo representam falhas do consumo.
🔴 400
🔴 401
🔴 403
🔴 404
🔴 409
🔴 422
🔴 500
{ "title":"Bad Request", "status":400, "detail":"Not possible to complete the request with the data provided"// Não foi possível concluir a solicitação com os dados fornecidos. }
{ "title":"Unauthorized", "status":401, "detail":"Authentication is required to access this resource"// É necessário autenticar-se para acessar este recurso. }
{ "title":"Forbidden", "status":403, "detail":"You do not have permission to access this resource"// Você não tem permissão para acessar este recurso. }
{ "title":"Not Found", "status":404, "detail":"The requested resource was not found"// O recurso solicitado não foi encontrado. }
{ "title":"Conflict", "status":409, "detail":"The request conflicts with the current state of the resource"// A solicitação entra em conflito com o estado atual do recurso. }
{ "title":"Unprocessable Entity", "status":422, "detail":"The request contains invalid or incomplete data"// A solicitação contém dados inválidos ou incompletos. }
{ "title":"Internal Server Error", "status":500, "detail":"Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible"// Nosso serviço está enfrentando um problema no momento. Pedimos desculpas pelo inconveniente e estamos trabalhando para resolvê-lo o mais rápido possível. }
As respostas de erro possuem os campos obrigatórios title, status e detail. O campo opcional extras pode conter informações adicionais.
Quando a cobrança retornar com o status waiting e o objeto tds_challenge, sua aplicação deverá apresentar o desafio à pessoa pagadora para que ela conclua a autenticação junto ao banco emissor.
O desafio poderá ser apresentado utilizando uma das opções abaixo:
html_template: HTML retornado pela API, que contém a estrutura necessária para executar o desafio.
form_data: dados para construir um formulário e enviá-lo pelo método POST à URL informada em action_url.
Seu servidor deverá encaminhar os dados de tds_challenge ao front-end. Os exemplos abaixo demonstram duas alternativas para apresentar o desafio. Utilize apenas uma delas.
Na opção html_template, crie um iframe e atribua à propriedade srcdoc o HTML completo retornado em tds_challenge.html_template. Adapte o local de exibição e as dimensões ao layout da sua aplicação.
Na opção form_data, crie um formulário com os dados retornados em tds_challenge.form_data. Envie os campos creq e threeDSSessionData exatamente como recebidos. O exemplo direciona a página atual para o ambiente de autenticação do banco emissor.
O campo challenge_callback_url, informado na criação da cobrança, define a URL de retorno da pessoa pagadora após o desafio.
Esse retorno poderá não ocorrer em situações como fechamento da página, perda de conexão ou abandono da autenticação. Sua aplicação deverá acompanhar a atualização da cobrança independentemente desse redirecionamento.
Atenção!
O retorno à URL informada em challenge_callback_url não confirma o pagamento da cobrança. Utilize as notificações da API como principal mecanismo de acompanhamento e a consulta pelo endpoint GET /v1/charge/:id como alternativa para verificar o status atualizado.
Para receber as notificações, informe a URL do seu servidor no campo metadata.notification_url ao criar a cobrança pelo endpoint POST /v1/charge/card. Essa URL recebe as atualizações de status e tem finalidade diferente de challenge_callback_url, utilizada para o retorno da pessoa pagadora após o desafio.
Quando houver um desafio 3DS, a atualização da cobrança ocorrerá de forma assíncrona. Enquanto o status estiver como waiting, sua aplicação deverá tratar a cobrança como pendente.
Utilize as notificações da API como principal mecanismo para acompanhar as alterações de status. Sua aplicação receberá uma requisição POST contendo o campo notification, com um token que deverá ser consultado pelo seu servidor para obter os dados atualizados da cobrança.
O histórico retornado nessa consulta apresenta as alterações em ordem cronológica. Utilize o último registro para identificar o status mais recente e o campo identifiers.charge_id para localizar a cobrança em seu sistema.
Após o processamento da autenticação, a cobrança poderá apresentar os seguintes status:
approved: pagamento aprovado, aguardando captura.
unpaid: pagamento não aprovado.
Para obter detalhes sobre o recebimento e a consulta do token, acesse a documentação de Notificações.
Caso seja necessário consultar a cobrança diretamente, utilize o endpoint GET /v1/charge/:id, informando o charge_id retornado na criação.
A pessoa pagadora deverá concluir o desafio de autenticação em até 10 minutos. Caso a autenticação não seja concluída nesse prazo, a cobrança será encerrada com o status unpaid.
O desafio também poderá ser interrompido em situações como fechamento da página ou do aplicativo, cancelamento da autenticação ou perda de conexão.
Nesses casos, sua aplicação deverá acompanhar a atualização da cobrança pelas notificações da API. O fechamento da tela, por si só, não deve ser utilizado para definir o status da transação em seu sistema.
Enquanto a cobrança estiver com o status waiting, apresente uma mensagem informando que o pagamento está em processamento.
Caso a notificação não seja recebida após 10 minutos da emissão, consulte a cobrança pelo endpoint GET /v1/charge/:id para verificar o status atualizado.
Para testar o fluxo de autenticação 3DS, configure a biblioteca JavaScript com setEnvironment("sandbox") e envie a requisição para POST /v1/charge/card utilizando a URL base de homologação: https://cobrancas-h.api.efipay.com.br.
Nesse ambiente, o último dígito do número do cartão utilizado na geração do payment_token determina o resultado inicial da cobrança.
Final do cartão
Status
Resultado esperado
0
waiting
Retorna os dados para apresentação do desafio 3DS.
1
unpaid
Dados do cartão inválidos.
2
unpaid
Transação não autorizada por motivos de segurança.
3
unpaid
Transação não autorizada. Tente novamente mais tarde.
Para uma cobrança gerada com cartão de final 0, apresente o desafio utilizando os dados de tds_challenge. A tela de autenticação do ambiente de homologação solicitará um código de quatro dígitos.
Código terminado em 1, como 0001: simula a aprovação do desafio, com atualização da cobrança para approved.
Código com qualquer outro final, como 0002: simula a recusa do desafio, com atualização da cobrança para unpaid.
Após o envio do código, acompanhe a atualização da cobrança pelas notificações da API. O redirecionamento para challenge_callback_url não deve ser utilizado como confirmação do pagamento.
No ambiente de homologação, cobranças com o status waiting, criadas há mais de 2 minutos e sem conclusão do desafio, serão consideradas abandonadas pela rotina de simulação.
A cobrança será atualizada para unpaid, com o motivo DS - Sua transação não foi aprovada. Por favor, tente novamente., e a atualização será informada por notificação.
Simulação em homologação
O prazo de mais de 2 minutos é específico da simulação de abandono no ambiente de homologação. Ele não substitui o prazo de 10 minutos descrito para conclusão do desafio no fluxo de produção.
Criação de cobrança por cartão de crédito em One Step (Um passo)
Após obter o payment_token através do código Javascript ou do back-end, seu servidor enviará as informações dos itens, da transação e do cliente, juntamente com o payment_token, para a API Efí.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "installments":1,// número de parcelas em que o pagamento deve ser dividido "installment_value":5990,// valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00) "charge_id": numero_charge_id,// número da ID referente à transação gerada "status":"approved",// Indica que o pagamento foi aprovado pela operadora do cartão mas ainda não foi creditado. "total":5990,// valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00) "payment":"credit_card"// forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito") } }
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "installments":1,// número de parcelas em que o pagamento deve ser dividido "installment_value":5990,// valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00) "charge_id": numero_charge_id,// número da ID referente à transação gerada "status":"unpaid",// Indica que o pagamento foi reprovado. "refusal":{ "reason":"Sistema de segurança: Os dados e comportamentos de utilização do cartão se assemelham a práticas e cenários de alto risco para pagamentos online. Utilize outro cartão ou outro meio de pagamento.",// Mensagem que contém o motivo da recusa da transação. "retry":true// Indica se é possível tentar novamente a transação. }, "total":5990,// valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00) "payment":"credit_card"// forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito") } }
Criação de cobrança por cartão de crédito em Two Steps (Dois passos)
Nesta opção é necessário seguir dois passos, enviando o body da requisição com todos os atributos mínimos obrigatórios para a emissão da cobrança.
Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
Associe à forma de pagamento via boleto, informando o charge_id da transação e os dados do cliente.
A documentação continua com os procedimentos detalhados, mas lembre-se de instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Efí foi instalada.
Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). Nesse momento, você informará o nome do item/produto/serviço, o valor da transação, a quantidade e outras informações relevantes.
Após criá-la, será retornado o charge_id, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.
No momento da criação, a transação recebe o status new, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.
Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
As respostas abaixo representam Sucesso do consumo.
🟢 200
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "charge_id": numero_charge_id,// número da ID referente à transação gerada "status":"new",// cobrança gerada, aguardando definição da forma de pagamento "total":8900,// valor total da transação (em centavos, sendo 8900 = R$89,00) "custom_id":null,// identificador próprio opcional "created_at":"2021-06-01 14:58:46"// data e hora da criação da transação } }
Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento desejada - neste caso, será credit_card (cartão de crédito). Para tal, deverá ser informado o charge_id obtido ao criar a transação.
Nesta etapa, seu backend enviará o restante das informações da transação, junto com o payment_token para a API Efí.
Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
As respostas abaixo representam Sucesso do consumo.
🟢 200
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "installments":1,// número de parcelas em que o pagamento deve ser dividido "installment_value":8900,// valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00) "charge_id": numero_charge_id,// número da ID referente à transação gerada "status":"waiting",// forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando") "total":8900,// valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00) "payment":"credit_card"// forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito") } }
Pagamento realizado como Pessoa Jurídica (PJ)
O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso é necessário informar a Razão Social e o CNPJ da empresa pagadora no atributo juridical_person.
Relação de todos os possíveis status de uma transação
Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status de uma transação na API para fornecer as devidas tratativas em seu sistema.
Confira neste link todos os detalhes dos possíveis status das transações.
Callbacks (notificações) das transações da API para seu sistema
As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando um boleto for pago, por exemplo.
Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.
Arredondamento de tarifa do cartão e-commerce
A formatação da tarifa é feita com number_format, ou seja, um arredondamento simples. Valores menores que 5 é arredondado para baixo, valores maiores ou igual a 5 o arredondamento é para cima.
Exemplo: Tarifa de 3,342 é arredondado para baixo 3,34 Tarifa de 3,335 vai ser arredondado para cima 3,34
Os pagamentos realizados via cartão de crédito, que forem recusados por algum motivo operacional, como falta de limite, dados incorretos e problemas temporários com o cartão, poderão ter uma nova tentativa de pagamento via API.
Dessa forma, não será necessário realizar todo o processo de emissão da cobrança novamente, tornando o fluxo mais rápido e eficiente.
POST /v1/charge/:id/retry
Requer ativação da API de Emissão de cobranças em sua aplicação
As respostas abaixo representam Sucesso do consumo.
🟢 200
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "installments":1,// número de parcelas em que o pagamento deve ser dividido "installment_value":8900,// valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00) "charge_id": numero_charge_id,// número da ID referente à transação gerada "status":"waiting",// forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando") "total":8900,// valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00) "payment":"credit_card"// forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito") } }
Informação
Esta funcionalidade permite que o integrador tente reprocessar uma cobrança que falhou. Para isso, a cobrança deve atender aos seguintes critérios:
Para retornar informações de uma transação, você deve enviar uma requisição GET para a rota /v1/charge/:id, onde :id é o charge_id da transação desejada.
GET /v1/charge/:id
Requer ativação da API de Emissão de cobranças em sua aplicação
Requisição
Dados de entrada
Parâmetro de entrada: informe a "charge_id" da transação desejada
Respostas
As respostas abaixo representam Sucesso(200) do consumo.
🟢 200
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "charge_id":391,// número da ID referente à transação gerada "total":2500,// valor total da transação (em centavos, sendo 2500 = R$25,00) "status":"unpaid",//não foi possível confirmar o pagamento da cobrança. O termo "unpaid" equivale a "não pago". "reason":"Número do cartão inválido.",//motivo da recusa do cartão "custom_id":null,// identificador próprio opcional "created_at":"2022-08-16 11:33:52",// data e hora da criação da transação "notification_url":null, "items":[ { "name":"Product 1",// nome de seu item, produto ou serviço "value":150,// valor, em centavos. Por exemplo: 150 (equivale a R$ 1,50) "amount":10// quantidade do item ou produto } ], "history":[ { "message":"Cobrança criada", "created_at":"2022-08-16 11:33:52" }, { "message":"Pagamento via cartão de crédito aguardando confirmação", "created_at":"2022-08-16 11:33:52" }, { "message":"Falha no pagamento - Número do cartão inválido.", "created_at":"2022-08-16 11:35:47" } ], "shippings":[ { "name":"Sedex", "value":1000, "payee_code":"473f6abd05d8a850a046395ed5544138" } ], "customer":{ "name":"Gorbadoc Oldbuck", "cpf":"65366950031", "birth":"1977-01-15", "email":"[email protected]", "phone_number":"5144916523" }, "payment":{ "method":"credit_card", "created_at":"2022-08-16 11:33:52", "message":null, "credit_card":{ "mask":"544969XXXXXX8502", "installments":1, "installment_value":2500, "address":{ "street":"Street 3", "number":"10", "complement":null, "neighborhood":"Bauxita", "city":"Ouro Preto", "state":"MG", "zipcode":"35400000" } } } } }
Para retornar as informações das cobranças emitidas em uma aplicação, você deve enviar uma requisição GET para a rota /v1/charges.
Este endpoint possui filtros para afunilar os resultados da busca, tais como CPF/CNPJ e status. Dentre todos os filtros disponíveis, os filtros charge_type, begin_date e end_date são obrigatórios e representam o tipo da transação e o intervalo de datas em que as cobranças consultadas devem estar compreendidas.
Importante!
Atualmente este recurso está em versão beta. Estamos entusiasmados em compartilhar essa ferramenta com você, porém, é essencial lembrar que ela está em desenvolvimento ativo e pode passar por alterações durante este período.
Valorizamos profundamente seu feedback durante esta fase e queremos ouvir suas experiências e sugestões para aprimorar continuamente nossos serviços. Sinta-se à vontade para entrar em contato conosco por meio de nossa comunidade do Discord ou outros canais de suporte.
GET /v1/charges
Requer ativação da API de Emissão de cobranças em sua aplicação
Assim como todos os endpoints de nossa API, a listagem de cobranças também possui um limite diário, que pode ser conferido na aba Limites de Consumo.
Caso as consultas excedam estes valores, recomendamos abrir um ticket em sua conta, solicitando a liberação.
Incluir "notification_url" e "custom_id" em uma transação existente
Você pode definir ou modificar as informações enviadas na propriedade metadata da transação a qualquer momento. Este endpoint é de extrema importância para atualizar a URL de notificação vinculada às transações ou modificar o custom_id associado anteriormente.
Para alterar a notification_url e/ou custom_id de uma transação, você deve enviar uma requisição PUT para a rota /v1/charge/:id/metadata, onde :id é o charge_id da transação desejada.
Casos de uso deste endpoint:
A pessoa integradora alterou o IP do servidor que estava associado à URL de notificação das transações;
A pessoa integradora atualizou a URL de notificação para as novas transações que forem criadas (createCharge), mas precisa atualizar também as transações anteriores (updateChargeMetadata) que foram geradas e que estão associadas com a URL incorreta/desatualizada;
Foi instalado SSL (https) no servidor do cliente e mesmo que o cliente defina uma regra de redirecionamento 301 ou 302, será necessário definir a nova URL nas transações que estão usando a URL "antiga";
A pessoa integradora gerou cobranças sem informar a URL de notificação ao enviar a requisição de criação da transação;
Modificar ou acrescentar uma informação junto ao atributo custom_id associado às transações geradas previamente;
Dentre outros possíveis cenários.
PUT /v1/charge/:id/metadata
Requer ativação da API de Emissão de cobranças em sua aplicação
Uma transação pode ser cancelada apenas se ela possuir o status new, waiting, unpaid ou link.
Quando uma transação é cancelada, existe apenas uma condição para que o status seja alterado novamente: se o cliente imprimir o boleto antes que a pessoa integradora cancele a transação, ele poderá realizar o pagamento normalmente em uma agência bancária. Nesse caso, tanto a pessoa integradora quanto a pagadora recebem a confirmação do pagamento, e o status da cobrança é alterado de canceled para paid.
Para cancelar uma transação, como um boleto, você deve enviar uma requisição PUT para a rota /v1/charge/:id/cancel, onde :id é o charge_id da transação que você deseja cancelar.
PUT /v1/charge:id/cancel
Requer ativação da API de Emissão de cobranças em sua aplicação
Requisição
Dados de entrada
Parâmetro de entrada: informe a "charge_id" da transação desejada
Respostas
As respostas abaixo representam Sucesso(200) do consumo.
🟢 200
{ "code":200// retorno HTTP "200" informando que o pedido foi bem sucedido }
Acrescentar descrição ao histórico de uma transação
O histórico de uma transação mostra todas as ações que ocorreram até o momento, mas as mensagens personalizadas não afetam a transação em si, apenas aparecem no histórico.
Este pode ser visualizado tanto no detalhamento da transação pela interface quanto usando o endpoint de detalhes da transação.
Você pode visualizar o histórico tanto na interface de detalhes da transação quanto usando o endpoint de detalhes da transação.
Você pode visualizar o histórico da transação na interface ou usando o endpoint de detalhes da transação. Para isso, basta enviar o identificador charge_id e a mensagem que deseja adicionar ao histórico da transação. A descrição deve ter entre 1 e 255 caracteres.
POST /v1/charge/:id/history
Requer ativação da API de Emissão de cobranças em sua aplicação
Requisição
Dados de entrada
{ "description":"Camisa Polo tamanho G cor azul, cobrança Bolix, pix com boleto." }
Respostas
As respostas abaixo representam Sucesso do consumo.
🟢 200
{ "code":200// retorno HTTP "200" informando que o pedido foi bem sucedido }
Listar parcelas de acordo com a bandeira do cartão
O endpoint installments é utilizado para listar as parcelas de cada bandeira de cartão de crédito, já com os valores de juros e número de parcelas calculados de acordo com a conta integradora. Ou seja, se a sua conta possui uma configuração de juros para cartão de crédito (opção disponível para clientes que optaram por receber pagamentos de forma parcelada), você não precisa fazer nenhum cálculo adicional, pois esse endpoint já fornece os valores calculados automaticamente.
Bandeiras disponíveis: visa, mastercard, amex e elo.
GET /v1/installments
Requer ativação da API de Emissão de cobranças em sua aplicação
Requisição
Dados de entrada
Parâmetro de entrada: informe o "brand" (bandeira) e o "total" (valor total da compra) desejado
Respostas
A resposta abaixo representa Sucesso(200) do consumo.
🟢 200
{ "code":200,// retorno HTTP "200" informando que o pedido foi bem sucedido "data":{ "rate":0, "name":"visa",// bandeira do cartão informada "installments":[ { "installment":1, "has_interest":false, "value":1000,// valor da primeira parcela "currency":"10,00", "interest_percentage":0 }, { "installment":2, "has_interest":true, "value":515,// valor da segunda parcela "currency":"5,15", "interest_percentage":199 } ] } }
Em determinadas situações, uma transação de cartão de crédito pode ser recusada pela adquirente.
Essas mensagens de retorno são enviadas diretamente pelas bandeiras ou pelas próprias adquirentes, conforme regras do mercado.
Ex: "51 - Transação não autorizada, entre em contato com o emissor do cartão.”
Esses códigos seguem o padrão definido pela ABECS (Associação Brasileira das Empresas de Cartões de Crédito e Serviços), conforme o normativo publicado em 15 de julho de 2020, que padroniza os códigos de retorno para transações de vendas recusadas.
Para acessar a tabela oficial, com todos os códigos possíveis de retorno, acesse o site da ABECS em Normativo ABECS.
Os códigos de retorno mais recorrentes são:
Código
Mensagem
Código ABECS
51
Transação não autorizada, entre em contato com o emissor do cartão
Saldo/Limite insuficiente
83
Transação não autorizada, entre em contato com o emissor do cartão
Senha vencida/inválida
Outros retornos recorrentes são:
A mensagem “Transação não autorizada. Cartão inválido” é retornada em caso de possível erro de digitação ou para cartão vencido.
A mensagem “Transações não autorizada, utilize outro método de pagamento” é retornada em caso de transação considerada com suspeita de alto risco, por análise do Efí ou da adquirente.
Atenção!
Tokenização de cartão
Atenção
Pagamento realizado como Pessoa Jurídica (PJ)
Relação de todos os possíveis status de uma transação
Informação