Esta biblioteca JavaScript permite uma solução segura e eficiente para manipular dados de cartão de crédito em seus projetos. Além disso, a criptografia dos dados diretamente no front-end da aplicação aumenta a segurança da transação e protege as informações do cartão contra interceptações maliciosas. Também é possível identificar a bandeira do cartão e obter informações de parcelamento.

Ir para:

• Demonstração
• Instalação
  • Web
  • Gerenciador de pacote
    • UMD
    • ES Modules
    • CommonJS
  • Framework React Native e outros (WebView)
  • Tipagens TypeScript
• Utilização
  • Exemplos práticos
  • Verificar bloqueio do script
  • Identificar a bandeira
  • Buscar as informações de parcelamento
  • Gerar o payment_token e card_mask
  • Dados de saída em caso de falha
• Criação da cobrança
• Documentação Adicional
• Comunidade e suporte
• Licença

Demonstração

Para ilustrar a utilização desta biblioteca em um contexto prático, você pode conferir uma demonstração neste link.

Instalação

Abaixo, fornecemos algumas opções de instalação da biblioteca para atender a projetos web que utilizam JavaScript puro ou frameworks modernos.

Web (Browser)

Realize o download da biblioteca localizada em /dist/payment-token-efi-umd.min.js para importação local, ou utilize a importação através do link do CDN.

• Importação local

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

• Importação por CDN

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

  Obs: neste tipo de aplicação, utilize o módulo umd.

Gerenciador de pacote (NPM ou Yarn)

Se você estiver utilizando um gerenciador de pacotes como npm ou yarn, instale a biblioteca diretamente:

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

Após a instalação, você pode importar a biblioteca conforme o ambiente que estiver utilizando:

Universal Module Definition (UMD)

Para ambientes que suportam Universal Module Definition:

import EfiPay from "payment-token-efi";

ECMAScript Modules (ESM)

Para ambientes que suportam ES Modules:

import EfiPay from "payment-token-efi";

CommonJS (CJS)

Para ambientes que utilizam o padrão CommonJS:

const EfiPay = require("payment-token-efi");

Obs: Esta biblioteca não é compatível no backend em Node.js

Framework React Native e outros (WebView)

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.

Tipagens TypeScript

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

Utilização

Este script traz quatro funções que ajudam no processamento de dados de cartão de crédito:

1. A primeira função permite verificar se o script foi bloqueado por alguma extensão ou configuração do navegador.
2. A segunda função identifica a bandeira do cartão a partir do número digitado.
3. A terceira função busca as opções de parcelamento com base nas configurações da sua conta.
4. E por fim, a quarta função gera o token de pagamento (payment_token) e a máscara do cartão (card_mask) usando os dados preenchidos.

Para utilizar esse script, é necessário passar 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 (veja onde encontrar), no menu API > Introdução > Identificador de Conta.

Exemplos práticos

Disponibilizamos alguns exemplos de utilização para as principais linguaguagens de progração front-end. Acesse aqui.

Verificar bloqueio 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.

• Exemplo:

  async function checkScriptBlocking() {
    const isBlocked = await EfiPay.CreditCard.isScriptBlocked();
  
    if (isBlocked) {
      console.log("O script está bloqueado!");
    } else {
      console.log("O script não está bloqueado.");
    }
  }

• Dados de saída:

  | Descrição | Tipo | | ------------------------------------------------------------------------- | ------- | |true se o script de fingerprint estiver bloqueado, false caso contrário. | boolean |

Identificar a bandeira

Função que identifica a bandeira do cartão pelo número, com base nas bandeiras aceitas pelo Efí.

• Dados de entrada:

  | Parâmetro/Método | Descrição | Tipo | Obrigatório | | ---------------- | --------------------------- | ------- | ----------- | | setCardNumber | Número do cartão de crédito | string | Sim | | debugger | Depurador de código | boolean | Não |

• Exemplo:

  async function identifyBrand() {
    try {
      const brand = await EfiPay.CreditCard
        .setCardNumber("4485785674290087")
        .verifyCardBrand();
  
      console.log("Bandeira: ", brand);
    } catch (error) {
      console.log("Código: ", error.code);
      console.log("Nome: ", error.error);
      console.log("Mensagem: ", error.error_description);
    }
  }

• Dados de saída:

  | Parâmetro | Descrição | Tipo | | --------- | --------------------------------------------------------------------------------------------------------------- | ------ | | brand | Brandeira do cartão. "undefined", "unsupported", "visa", "mastercard", "amex", "elo", "hipercard" | string |

Buscar as informações de parcelamento

Função para buscar as informações de parcelamento de acordo com as configurações de recebimento em sua conta.

• Dados de entrada:

  | Parâmetro/Método | Descrição | Tipo | Obrigatório | | ---------------- | ----------------------------------------------------------------------------- | ------- | ----------- | | setAccount | Identificador de conta | string | Sim | | setEnvironment | Ambiente. "production" ou "sandbox" | string | Sim | | setBrand | Bandeira do cartão "visa", "mastercard", "amex", "elo", "hipercard" | string | Sim | | setTotal | Valor total | Integer | Sim | | debugger | Depurador de código | boolean | Não |

• Exemplo:

  async function listInstallments() {
    try {
      const installments = await EfiPay.CreditCard
        .setAccount("Identificador_de_conta_aqui")
        .setEnvironment("production") // 'production' or 'sandbox'
        .setBrand("visa")
        .setTotal(28990)
        .getInstallments();
  
        console.log("Parcelas", installments);
    } catch (error) {
      console.log("Código: ", error.code);
      console.log("Nome: ", error.error);
      console.log("Mensagem: ", error.error_description);
    }
  }

• Dados de saída:

  | Parâmetro | Descrição | Tipo | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | | installments | Array com as parcelas. {"rate": 0,"name": "brand","installments": [{"installment": 1,"has_interest": false,"value": 500,"currency": "5,00","interest_percentage": 0}]} | object |

Gerar o payment_token e card_mask

Função que gera o payment_token, um código criado pela API da Efí que representa os dados do cartão da pessoa pagadora, e também a card_mask, com base nas informações do cartão.

• Dados de entrada:

  | Parâmetro/Método | Descrição | Tipo | Obrigatório | | ----------------- | ---------------------------------------------------------------- | ------- | ----------- | | setAccount | Identificador de conta | string | Sim | | setEnvironment | Ambiente. "production" ou "sandbox" | string | Sim | | setCreditCardData | Dados do cartão de crédito | object | Sim | | - | brand "visa", "mastercard", "amex", "elo", "hipercard" | string | Sim | | - | number | string | Sim | | - | cvv | string | Sim | | - | expirationMonth 'MM' | string | Sim | | - | expirationYear 'YYYY' | string | Sim | | - | holderName 'Nome impresso no cartão' | string | Não | | - | holderDocument CPF ou CPNJ | string | Não | | - | reuse | boolean | Não | | debugger | Depurador de código | boolean | Não |

• Exemplo:

  async function generatePaymentToken() {
    try {
      const result = await EfiPay.CreditCard
        .setAccount("Identificador_de_conta_aqui")
        .setEnvironment("production")
        .setCreditCardData({
          brand: "visa",
          number: "4485785674290087",
          cvv: "123",
          expirationMonth: "05",
          expirationYear: "2029",
          holderName: "Gorbadoc Oldbuck",
          holderDocument: "94271564656",
          reuse: false,
        })
        .getPaymentToken();
  
      const payment_token = result.payment_token;
      const card_mask = result.card_mask;
  
      console.log("payment_token", payment_token);
      console.log("card_mask", card_mask);
    } catch (error) {
      console.log("Código: ", error.code);
      console.log("Nome: ", error.error);
      console.log("Mensagem: ", error.error_description);
    }
  }

• Dados de saída:

  | Parâmetro | Descrição | Tipo | | ------------- | ---------------------------------------------------- | ------ | | payment_token | Token de pagamento que representa o cartão utilizado | string | | card_mask | Máscara do cartão utilizado | string |

Ativar debbuger

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

EfiPay.CreditCard.debugger(true);

Dados de saída em caso de falha

Em caso de erro, será retornado no try/catch o objeto com os parâmetros descritos abaixo.

| Parâmetro | Descrição | Tipo | | ----------------- | ------------------------------------ | ------ | | code | Código de erro para identificação. | string | | error | Nome do erro. | string | | error_description | Mensagem detalhando o erro ocorrido. | string |

Criação da cobrança

Após a obtenção do payment_token será possível emitir a cobrança de cartão de crétito. Acesse nossa documentação técnica para mais detalhes.

Para criar cobranças de cartão de crédito, lembre-se de registrar o ramo de atividades em sua conta Efí. Veja como.

Documentação Adicional

Acesse nossa documentação técnica para ver todas as informações das APIs Efí Pay.

Se você ainda não tem uma conta digital da Efí, abra a sua agora!

Comunidade e suporte

Faça parte da comunidade Efí e conecte-se a milhares de desenvolvedores, participe de discussões, tire dúvidas e integre suas operações às APIs Efí (API Pix, API Boletos e Cartão, e muito mais) com a ajuda da maior comunidade de integradores de meios de pagamentos do Brasil.

Licença

MIT