js-payment-token-efi

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #llm #machine-learning #linux #docker #macos #java #awesome-list #mcp #ios #open-source

js-payment-token-efi

(★ 11)

Biblioteca Javascript que permite a criptografia dos dados do cartão do cartão a partir do browser do cliente para gerar o payment_token e identificar a bandeira do cartão.

js-payment-token-efi Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>Script payment_token cartão de crédito | Efí</h1>

[![NPM Version](https://img.shields.io/npm/v/payment-token-efi.svg)](https://www.npmjs.com/package/payment-token-efi)
[![NPM Downloads](https://img.shields.io/npm/dm/payment-token-efi.svg)](https://www.npmjs.com/package/payment-token-efi)
[![](https://data.jsdelivr.com/v1/package/npm/payment-token-efi/badge)](https://www.jsdelivr.com/package/npm/payment-token-efi)
[![License](https://img.shields.io/npm/l/payment-token-efi.svg)](https://github.com/efipay/js-payment-token-efi/blob/main/LICENSE)

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**](#demonstração)
- [**Instalação**](#instalação)
  - [**Web**](#web-browser)
  - [**Gerenciador de pacote**](#gerenciador-de-pacote-npm-ou-yarn)
  	- [**UMD**](#universal-module-definition-umd)
  	- [**ES Modules**](#ecmascript-modules-esm)
  	- [**CommonJS**](#commonjs-cjs)
  - [**Framework React Native e outros (WebView)**](#framework-react-native-e-outros-webview)
  - [**Tipagens TypeScript**](#tipagens-typescript)
- [**Utilização**](#utilização)
	- [**Exemplos práticos**](#exemplos-práticos)
	- [**Verificar bloqueio do script**](#verificar-bloqueio-do-script)
	- [**Identificar a bandeira**](#identificar-a-bandeira)
	- [**Buscar as informações de parcelamento**](#buscar-as-informações-de-parcelamento)
	- [**Gerar o payment_token e card_mask**](#gerar-o-payment_token-e-card_mask)
	- [**Dados de saída em caso de falha**](#dados-de-saída-em-caso-de-falha)
- [**Criação da cobrança**](#criação-da-cobrança)
- [**Documentação Adicional**](#documentação-adicional)
- [**Comunidade e suporte**](#comunidade-e-suporte)
- [**Licença**](#licença)

---

## **Demonstração**

Para ilustrar a utilização desta biblioteca em um contexto prático, você pode conferir uma demonstração [neste link](https://efipay.github.io/js-payment-token-efi/).

![Demonstração geerando um payment_token](https://sejaefi.link/rygrqiv3DR)

---

## **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](https://raw.githubusercontent.com/efipay/js-payment-token-efi/main/dist/payment-token-efi-umd.min.js) 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**
  ```html
  <script src="./dist/payment-token-efi-umd.min.js"></script>
  ```
- **Importação por CDN**
  ```html
  <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:
Se você estiver utilizando um gerenciador de pacotes como npm ou yarn, instale a biblioteca diretamente ([acesse no NPM](https://www.npmjs.com/package/payment-token-efi)):

```sh
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:

```javascript
import EfiPay from "payment-token-efi";
```

#### **ECMAScript Modules (ESM)**

Para ambientes que suportam ES Modules:

```javascript
import EfiPay from "payment-token-efi";
```

#### **CommonJS (CJS)**

Para ambientes que utilizam o padrão CommonJS:

```javascript
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](https://github.com/efipay/js-payment-token-efi/blob/main/examples/webview-react-native.js) 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 <ins>**[verificar se o script foi bloqueado](#verificar-bloqueio-do-script)**</ins> por alguma extensão ou configuração do navegador.
2. A segunda função <ins>**[identifica a bandeira do cartão](#identificar-a-bandeira)**</ins> a partir do número digitado.
3. A terceira função <ins>**[busca as opções de parcelamento](#buscar-as-informações-de-parcelamento)**</ins> com base nas configurações da sua conta.
4. E por fim, a quarta função <ins>**[gera o token de pagamento (payment_token) e a máscara do cartão (card_mask)](#gerar-o-payment_token-e-card_mask)**</ins> 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 (<a href='https://s3.amazonaws.com/gerencianet-pub-prod-1/printscreen/2023/03/08/matheus.rodrigues/24fa15-dda30019-a643-409e-8813-c7cc68adcc40.png' target='_blank'>veja onde encontrar</a>), 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](https://github.com/efipay/js-payment-token-efi/tree/main/examples).

### **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:**

```js
  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í](https://dev.efipay.com.br/docs/api-cobrancas/cartao#confira-a-lista-de-cart%C3%B5es-de-cr%C3%A9dito-aceitos-pela-ef%C3%AD).

- **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:**

```js
    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 |

<br>

### **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](https://app.sejaefi.com.br/configuracoes-da-conta/configuracoes-de-cobrancas/cartao-de-credito).

- **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:**

```js
    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 |

<br>

### **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:**

```js
    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.

```js
  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 |

<br>

---

## **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](https://dev.efipay.com.br/docs/api-cobrancas/cartao#cria%C3%A7%C3%A3o-de-cobran%C3%A7a-por-cart%C3%A3o-de-cr%C3%A9dito-em-one-step-um-passo) 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](https://sejaefi.com.br/central-de-ajuda/dados-cadastrais/inserir-ramo-de-atividade#conteudo).

---

## **Documentação Adicional**

[Acesse nossa documentação técnica](https://dev.efipay.com.br/)</a> 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](https://sejaefi.com.br/)!

---

## **Comunidade e suporte**

[Faça parte da comunidade Efí](https://comunidade.sejaefi.com.br/) 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](LICENSE)

js-payment-token-efi

js-payment-token-efi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

js-payment-token-efi

js-payment-token-efi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README