@be.izi/card-tokenization

SDK para tokenizar cartões de pagamento no navegador usando a infraestrutura da Beizi. O pacote é independente de framework e oferece tipos para TypeScript.

Os dados do cartão são enviados diretamente do navegador para o serviço de tokenização. Sua aplicação recebe um cardToken, que deve ser enviado ao backend para realizar a operação de pagamento.

Instalação

npm install @be.izi/card-tokenization

Antes de começar

Você precisa de:

• uma chave de tokenização fornecida pela Beizi;
• a origem da aplicação cadastrada para essa chave;
• um ambiente de navegador. A tokenização não pode ser executada no servidor.

Uso básico

import { Beizi } from '@be.izi/card-tokenization';

const beizi = Beizi.create({
  tokenizationKey: 'sua_chave_de_tokenizacao',
  environment: 'HOM',
});

const result = await beizi.tokenize({
  number: '4111 1111 1111 1111',
  holder: 'MARIA DA SILVA',
  expiryMonth: '12',
  expiryYear: '2030',
  cvv: '123',
});

// Envie somente o token ao seu backend.
await sendToYourBackend({ cardToken: result.cardToken });

O resultado da tokenização contém:

| Campo | Descrição | | ---------------- | ----------------------------------------------------------------- | | cardToken | Token que representa os dados do cartão na operação de pagamento. | | brand | Bandeira identificada: VISA, MASTERCARD, ELO ou AMEX. | | lastFourDigits | Quatro últimos dígitos do cartão. | | expiresAt | Data e hora de expiração do token. |

Cobrança pública

Quando a tokenização estiver associada a uma cobrança pública, informe o contexto com o identificador da cobrança:

const result = await beizi.tokenize({
  number: '4111 1111 1111 1111',
  holder: 'MARIA DA SILVA',
  expiryMonth: '12',
  expiryYear: '2030',
  cvv: '123',
  context: {
    type: 'PUBLIC_CHARGE',
    chargeId: 'identificador_da_cobranca',
  },
});

Omita context nas tokenizações vinculadas diretamente à conta.

Tratamento de erros

Falhas de validação, configuração ou comunicação são representadas por TokenizationError:

import { Beizi, TokenizationError } from '@be.izi/card-tokenization';

try {
  const result = await beizi.tokenize(card);
  await sendToYourBackend({ cardToken: result.cardToken });
} catch (error) {
  if (error instanceof TokenizationError) {
    console.error(error.code, error.field);

    if (error.retryable) {
      // Permita que a pessoa tente novamente. Não faça retry automático.
    }
  }
}

Cada erro expõe:

| Propriedade | Descrição | | ----------- | ------------------------------------------------------------------- | | code | Código estável que identifica a falha. | | field | Campo inválido, quando a falha está associada a um campo do cartão. | | retryable | Indica se uma nova tentativa manual pode ser oferecida. |

Códigos disponíveis:

| Código | Significado | | ------------------------------ | ---------------------------------------------------------- | | BROWSER_ENVIRONMENT_REQUIRED | A tokenização foi chamada fora do navegador. | | INVALID_HOLDER | Nome do titular inválido. | | INVALID_CARD_NUMBER | Número do cartão inválido. | | INVALID_EXPIRY | Mês ou ano de validade inválido. | | INVALID_CVV | Código de segurança inválido. | | INVALID_CONTEXT | Contexto de tokenização inválido. | | UNSUPPORTED_CARD_BRAND | Bandeira não suportada. | | INVALID_TOKENIZATION_KEY | Chave de tokenização inválida. | | ORIGIN_NOT_ALLOWED | Origem da aplicação não autorizada. | | RATE_LIMITED | Limite temporário de requisições atingido. | | TIMEOUT | O serviço não respondeu dentro do tempo esperado. | | NETWORK_ERROR | Não foi possível acessar o serviço de tokenização. | | SERVICE_UNAVAILABLE | Serviço temporariamente indisponível ou resposta inválida. |

RATE_LIMITED, TIMEOUT, NETWORK_ERROR e SERVICE_UNAVAILABLE possuem retryable: true.

Ambientes

| Valor | Uso | | ----- | ------------------------- | | HOM | Integração e homologação. | | PRD | Produção. |

Não existe ambiente padrão: informe sempre environment ao criar o cliente.

Segurança

• Nunca registre ou persista PAN, CVV, nome do titular, chave de tokenização ou cardToken.
• Não envie os dados brutos do cartão ao seu backend. Envie somente cardToken.
• Use apenas dados sintéticos em testes, exemplos e ferramentas de diagnóstico.
• Não faça retry automático de uma tokenização.

Consulte a política de segurança para mais orientações.