Cartão

Passo a passo para gerar uma cobrança de cartão de crédito na API Efí

Introdução

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
Hipercard

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.

Obtenção do payment_token

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

A simulação de cobranças de cartão em ambiente de Homologação funciona com base na análise imediata de acordo com o último dígito do número do cartão de crédito 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.

Biblioteca JavaScript

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.

Demonstração

Para visualizar como essa biblioteca é utilizada em um exemplo prático, você pode conferir uma demonstração aqui.

Veja mais detalhes no repositório da biblioteca no GitHub.

Instalação

Aqui estão algumas opções para instalar a biblioteca em projetos web que usam JavaScript puro ou tecnologias como o Node.js. Veja os detalhes a seguir:

a) Aplicação Web

Disponibilizamos duas formas de instalação da biblioteca em aplicações Web.

Importação por CDN

Importação através do link do CDN da biblioteca.

script

  <script src="https://cdn.jsdelivr.net/gh/efipay/js-payment-token-efi/dist/payment-token-efi.min.js"></script>

Importação local

Realizando o download da biblioteca localizada em /dist/payment-token-efi.min.js, adicione-a localmente em seu projeto.

script

  <script src="./dist/payment-token-efi.min"></script>

b) Aplicação Node

Para usar a biblioteca em um cenário Node.js, você tem duas opções de instalação.

Importação por NPM

Utilize o gerenciador de pacotes NPM para instalar a biblioteca com o seguinte comando:

Linha de comando

  npm i payment-token-efi   
  // ou
  yarn add payment-token-efi    

Após a instalação da biblioteca, basta importá-la em seu projeto.

Código

  const EfiJs = require('payment-token-efi');

Importação local

A segunda opção é baixar o arquivo/distNode/payment-token-efi.js e importá-la localmente.

Código

  const EfiJs = require('./distNode/payment-token-efi');

Depois, basta instalar a seguinte biblioteca como dependência para a virtualização do DOM.

Linha de comando

  npm install jsdom --save
  // ou
  yarn add jsdom

Utilização

Este script oferece três funções para manipulação de dados de cartão de crédito. A primeira função permite identificar a bandeira do cartão a partir do seu número. A segunda função busca informações de parcelamento de acordo com as configurações de recebimento via cartão em sua conta. Por fim, a terceira função gera o token de pagamento (payment_token) e a máscara do cartão (card_mask) com base nos dados do cartão.

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) Identificar a bandeira

Identificar a bandeira

Função para identificar a bandeira

Requisição

Código

try {
    EfiJs.CreditCard
      .setCardNumber('4485785674290087')
      .verifyCardBrand()
      .then(brand => {
          console.log('Bandeira: ', brand);

          if (brand !== 'undefined') {
              // Exemplo: executar a função para gerar o payment_token com a bandeira identificada
          }
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} 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

mastercard

b) Buscar as informações de parcelamento

Buscar as informações de parcelamento

Função para buscar as informações de parcelamento

Requisição

Código

try {
  EfiJs.CreditCard
      .setAccount('Identificador_de_conta_aqui')
      .setEnvironment('production') // 'production' or 'sandbox'
      .setBrand('visa')
      .setTotal(28990)
      .getInstallments()
      .then(installments => {
          console.log('Parcelas', installments);
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} 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

  {
    "rate": 0,
    "name": "brand",
    "installments": [{
        "installment": 1,
        "has_interest": false,
        "value": 500,
        "currency": "5,00",
        "interest_percentage": 0
    }]
  }

c) Gerar o payment_token e card_mask

Gerar o payment_token e card_mask

Função para gerar o payment_token e card_mask

Requisição

Código

try {
  EfiJs.CreditCard
      .setAccount('Identificador_de_conta_aqui')
      .setEnvironment('production') // 'production' or 'sandbox'
      .setCreditCardData({
          brand: 'visa',
          number: '4485785674290087',
          cvv: '123',
          expirationMonth: '05',
          expirationYear: '2029',
          reuse: false
      })
      .getPaymentToken()
      .then(data => {
          const payment_token = data.payment_token;
          const card_mask = data.card_mask;

          console.log('payment_token', payment_token);
          console.log('card_mask', card_mask);
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} 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"
  }

e) Ativar debbuger

Ativar debbuger

O debugger pode ser ativado para depurar e encontrar possível falhas.

Requisição

Código

EfiJs.CreditCard.debugger(true);

Respostas

Em caso de erro, será retornado no try/catch o objeto como apresentado abaixo.

🟢 200

 {
  "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', 'elo' ou 'hipercard'."
} 

Módulo jQuery

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:

Efetue login em sua conta Efí e acesse API.
Copie seu Identificador de conta (veja onde)
Cole no campo abaixo e clique no botão Gerar

Atenção!

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;
getInstallments: Retorna as informações sobre parcelamento de acordo com as configurações de recebimento em sua conta.

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.

🟢 200
🔴 Falha

{
  "code": 200,
  "data": {
      "payment_token": "47f13d72c883c1547ae4a0df11eb46194f333f85",
      "card_mask": "XXXXXXXXXXXX3991"
  }
}

{
  "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', 'elo' ou 'hipercard'."
}
Ou
{
  "code": 3500058,
  "error": "invalid_card_number",
  "error_description": "O parâmetro [number] informado é inválido."
}
Ou
{
  "code": 3500011,
  "error": "invalid_data",
  "error_description": {
      "property": "cvv",
      "message": "Cvv deve conter entre 3 e 4 caracteres"
  }
}
Ou
{
  "code": 3500062,
  "error": "invalid_expiration_month",
  "error_description": "O parâmetro [expiration_month] informado é inválido."
}
Ou
{
  "code": 3500011,
  "error": "invalid_data",
  "error_description": {
      "property": "expiration_year",
      "message": "Expiration year inválido"
  }
}

getInstallments

Função que retorna as informações sobre parcelamento

Respostas

As respostas abaixo representam Sucesso e Falha do consumo.

🟢 200
🔴 Falha

{
  "code": 200,
  "data": {
      "rate": 0,
      "name": "visa",
      "installments": [
          {
              "installment": 1,
              "has_interest": false,
              "value": 47988,
              "currency": "479,88",
              "interest_percentage": 0
          },
          {
              "installment": 2,
              "has_interest": false,
              "value": 23994,
              "currency": "239,94",
              "interest_percentage": 0
          },
          {
              "installment": 3,
              "has_interest": true,
              "value": 16637,
              "currency": "166,37",
              "interest_percentage": 199
          }
      ]
  }
}

{
  "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', 'elo' ou 'hipercard'."
}
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."
}

Back-end

Atençã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 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:

v1/charge/one-step

"items"
  "name"
  "value"
  "amount"
  "marketplace"
      "payee_code"
      "percentage"
"shippings"
  "name"
  "value"
  "payee_code"
"metadata"
  "custom_id"
  "notification_url"
"payment"
  "credit_card"
      "customer"
          "name"
          "cpf"
          "email"
          "phone_number"
          "birth"
          "address"
              "street"
              "number"
              "neighborhood"
              "zipcode"
              "city"
              "complement"
              "state"
          "juridical_person"
              "corporate_name"
              "cnpj"
      "installments"
      "discount"
          "type"
              "percentage",
              "currency"
          "value"
      "billing_address"
          "street"
          "number"
          "neighborhood"
          "zipcode"
          "city"
          "complement"
          "state"
      "payment_token"
      "message"

POST /v1/charge/one-step

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": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "email_do_cliente@servidor.com.br",
        "birth": "1990-08-29",
        "phone_number": "5144916523"
      },
      "installments": 1,
      "payment_token": "",
      "billing_address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "neighborhood": "Bauxita",
        "zipcode": "35400000",
        "city": "Ouro Preto",
        "complement": "",
        "state": "MG"
      }
    }
  }
}

Respostas

A resposta abaixo representa Sucesso do consumo.

🟢 200 (cartão)

{
  "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": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
    "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.

1. Criar transação

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:

v1/charge

"items"  
      "name"  
      "value"  
      "amount"  
      "marketplace"  
          "payee_code"  
          "percentage"  
  "shippings"  
      "name"  
      "value"  
      "payee_code"  
  "metadata"  
      "custom_id"  
      "notification_url"

POST /v1/charge

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": 8900,
      "amount": 1
    }
  ]
}

Respostas

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
  }
}

2. Associar à forma de pagamento via cartão

Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento desejada - neste caso, será banking_billet (boleto bancário). 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:

v1/charge/:id/pay

"payment"  
    "credit_card"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "installments"  
        "discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
        "billing_address"  
            "street"  
            "number"  
            "neighborhood"  
            "zipcode"  
            "city"  
            "complement"  
            "state"  
        "payment_token"  
        "message"

POST /v1/charge/:id/pay

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

{
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "email_do_cliente@servidor.com.br",
        "birth": "1990-08-29",
        "phone_number": "5144916523"
      },
      "installments": 1,
      "payment_token": "",
      "billing_address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "neighborhood": "Bauxita",
        "zipcode": "35400000",
        "city": "Ouro Preto",
        "complement": "",
        "state": "MG"
      }
    }
  }
}

Respostas

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

Retentativa de pagamento via cartão de crédito

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

Requisição

Dados de entrada

{
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "email_do_cliente@servidor.com.br",
        "birth": "1990-08-29",
        "phone_number": "5144916523"
      },
      "billing_address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "neighborhood": "Bauxita",
        "zipcode": "35400000",
        "city": "Ouro Preto",
        "complement": "",
        "state": "MG"
      },
      "payment_token": "75bfce47d230b550f7eaac2a932e0878a934cb3"
    }
  }
}

Respostas

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:

a cobrança deve ser de cartão de crédito

a cobrança deve ter o status unpaid

a cobrança não pode ser recorrente

Retornar informações de transação existente

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": "gustavo@uol.com.br",
      "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"
        }
      }
    }
  }
}

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

Requisição

Dados de entrada

{
  "notification_url": 'http://seu_dominio.com/notification',
  "custom_id": 'REF0001'
}

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 200

{
  "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Cancelar uma transação existente

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, elo e hipercard.

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
      }
    ]
  }
}

Cartão

Introdução​

Confira a lista de cartões de crédito aceitos pela Efí​

Obtenção do payment_token​

Biblioteca JavaScript​

Demonstração​

Instalação​

a) Aplicação Web​

b) Aplicação Node​

Utilização​

a) Identificar a bandeira​

b) Buscar as informações de parcelamento​

c) Gerar o payment_token e card_mask​

e) Ativar debbuger​

Módulo jQuery​

Obtendo um "payment_token" (getPaymentToken) e informações sobre parcelamentos (getInstallments)​

Atributos relacionados ao envio de dados do cartão e retorno das funcões​

Back-end​

Criação de cobrança por cartão de crédito em One Step (Um passo)​

Criação de cobrança por cartão de crédito em Two Steps (Dois passos)​

1. Criar transação​

2. Associar à forma de pagamento via cartão​

Retentativa de pagamento via cartão de crédito​

Retornar informações de transação existente​

Incluir "notification_url" e "custom_id" em uma transação existente​

Cancelar uma transação existente​

Acrescentar descrição ao histórico de uma transação​

Listar parcelas de acordo com a bandeira do cartão​

Introdução

Confira a lista de cartões de crédito aceitos pela Efí

Obtenção do payment_token

Biblioteca JavaScript

Demonstração

Instalação

a) Aplicação Web

b) Aplicação Node

Utilização

a) Identificar a bandeira

b) Buscar as informações de parcelamento

c) Gerar o payment_token e card_mask

e) Ativar debbuger

Módulo jQuery

Obtendo um "payment_token" (getPaymentToken) e informações sobre parcelamentos (getInstallments)

Atributos relacionados ao envio de dados do cartão e retorno das funcões

Back-end

Criação de cobrança por cartão de crédito em One Step (Um passo)

Criação de cobrança por cartão de crédito em Two Steps (Dois passos)

1. Criar transação

2. Associar à forma de pagamento via cartão

Retentativa de pagamento via cartão de crédito

Retornar informações de transação existente

Incluir "notification_url" e "custom_id" em uma transação existente

Cancelar uma transação existente

Acrescentar descrição ao histórico de uma transação

Listar parcelas de acordo com a bandeira do cartão