Safeway SDK

SDK oficial para criptografia e tokenização de cartões de crédito em integrações com a SafeWay.

Este pacote abstrai toda a complexidade do processo de criptografia, realizando a tokenização de forma transparente — sua aplicação chama uma única função e recebe o cartão pronto para uso.

Recursos

• Criptografia de cartão feita de forma automática
• Interface simples e tipada em TypeScript
• Retorno estruturado com status claro da operação

Instalação

# npm
npm install safeway-crypto-sdk

# yarn
yarn add safeway-crypto-sdk

# pnpm
pnpm add safeway-crypto-sdk

Como funciona

Antes de criptografar o cartão, sua aplicação deve chamar o endpoint de detalhamento de checkout na SafeWay para obter as credenciais do provedor ativo:

GET /deposits/credit-card/tokenization
// Authorization: {SEU_TOKEN_JWT}

Esse endpoint retorna informações e chaves para a criptografia desta transação.

Com essas informações em mãos, chame CreateCryptographedCard do SDK, passando o objeto do cartão de crédito e o retorno do endpoint acima. Esta função irá retornar um objeto contendo um Status e o hash do cartão (se obteve sucesso).

O hash retornado pode então ser enviado á confirmação de checkout na SafeWay.

Uso

import { CreateCryptographedCard } from 'safeway-crypto-sdk';

const result = await CreateCryptographedCard({
    // [dados de tokenização, obtidos pelo endpoint de tokenização]...,
    creditCard: {
        cardNumber: '1234567890123456',
        cardExpirationMonth: '02',
        cardExpirationYear: '2027',
        cardSecurityCode: '123',
        cardHolderName: 'Example User'
    }
});

if (result?.status === 'SUCCESS') {
    console.log('Cartão criptografado:', result.tokenizedCard);
}

API

CreateCryptographedCard(tokenizationData: TokenizationDTO): Promise<CryptographedData | undefined>

Função principal do SDK. Recebe os dados de tokenização e retorna o cartão criptografado/tokenizado.

Tipos

TokenizationDTO

| Campo | Tipo | Descrição | |-------|------|-----------| | code, publicKeyId, publicKey, createdAt, expiresAt, transactionalToken | - | Todos os dados retornados no objeto "tokenization", ao detalhar um checkout | | creditCard | CreditCardDTO | Dados do cartão de crédito para criptografar |

CreditCardDTO

| Campo | Tipo | Descrição | |-------|------|-----------| | cardNumber | string | Número do cartão (espaços são removidos automaticamente) | | cardExpirationMonth | string | Mês de vencimento (01–12) | | cardExpirationYear | string | Ano de vencimento (2 ou 4 dígitos) | | cardSecurityCode | string | Código de segurança (CVV) | | cardHolderName | string | Nome completo do titular |

CryptographedData

Retorno da função de criptografia.

| Campo | Tipo | Descrição | |-------|------|-----------| | status | "SUCCESS" | "FAILED" | Status da operação | | tokenizedCard | string | Dados criptografados ou token do cartão (presente em SUCCESS e INVALID_CVV) | | message | string | Mensagem descritiva do resultado |

Status de retorno

| Status | Descrição | |--------|-----------| | SUCCESS | Criptografia/tokenização realizada com sucesso | | FAILED | Falha no processo de tokenização |

Requisitos

• Node.js 18+
• TypeScript 5+ (para projetos TypeScript)

Licença

ISC