SDK de Integração com Adquirentes

Um SDK para integração com múltiplas adquirentes de pagamento, permitindo processar pagamentos com diferentes métodos (cartão de crédito, débito, boleto, PIX) usando uma interface padronizada, independentemente da adquirente utilizada.

Características

• Interface padronizada para todas as adquirentes
• Suporte a múltiplos métodos de pagamento
• Tratamento de erros consistente
• Logs detalhados para depuração
• Fácil de estender para novas adquirentes

Adquirentes Suportadas

• [x] Mercado Pago
• [x] PagSeguro
• [ ] Cielo (em breve)
• [ ] Stone (em breve)
• [ ] Iugu (em breve)

Métodos de Pagamento Suportados

• Cartão de Crédito
• Cartão de Débito
• Boleto
• PIX
• Carteira Digital (depende da adquirente)

Instalação

npm install sdk-adquirentes

Uso Básico

import { PaymentSDK } from 'sdk-adquirentes';

// Inicializa o SDK com as credenciais da adquirente
const sdk = new PaymentSDK('mercadopago', {
  accessToken: 'SEU_ACCESS_TOKEN',
  environment: 'sandbox' // ou 'production'
});

// Cria um pagamento
const payment = await sdk.createPayment({
  amount: 10000, // R$ 100,00 (em centavos)
  currency: 'BRL',
  description: 'Compra na loja XYZ',
  paymentMethod: {
    type: 'credit_card',
    installments: 1,
    token: 'TOKEN_OBTIDO_DO_FRONTEND' // Token obtido do frontend após tokenização
  },
  customer: {
    name: 'Fulano de Tal',
    email: '[email protected]',
    document: '12345678909',
    phone: '+5511999999999',
    address: {
      street: 'Rua Exemplo',
      number: '123',
      complement: 'Apto 101',
      neighborhood: 'Centro',
      city: 'São Paulo',
      state: 'SP',
      zipCode: '01001000',
      country: 'BR'
    }
  }
});

console.log(`Pagamento criado: ${payment.id}`);
console.log(`Status: ${payment.status}`);

Exemplos

Pagamento com Cartão de Crédito (usando token)

Para processar pagamentos com cartão, você deve primeiro obter um token do cartão usando a SDK de frontend da adquirente:

// Frontend: Obtenção do token (exemplo com Mercado Pago)
const cardToken = await mercadopago.createCardToken({
  cardNumber: '4111111111111111',
  cardholderName: 'FULANO DE TAL',
  cardExpirationMonth: '12',
  cardExpirationYear: '2025',
  securityCode: '123'
});

// Backend: Uso do token no SDK
const payment = await sdk.createPayment({
  amount: 10000,
  currency: 'BRL',
  description: 'Compra na loja XYZ',
  paymentMethod: {
    type: 'credit_card',
    installments: 3,
    token: cardToken.id // Token obtido do frontend
  },
  customer: {
    name: 'Fulano de Tal',
    email: '[email protected]',
    document: '12345678909'
    // ... outros dados do cliente
  }
});

Pagamento com PIX

const payment = await sdk.createPayment({
  amount: 10000,
  currency: 'BRL',
  description: 'Compra na loja XYZ',
  paymentMethod: {
    type: 'pix'
  },
  customer: {
    name: 'Fulano de Tal',
    email: '[email protected]',
    document: '12345678909'
    // ... outros dados do cliente
  }
});

// Acessa os dados do PIX
const pixData = payment.paymentMethod.pix;
console.log(`QR Code: ${pixData.qrcode}`);
console.log(`URL do QR Code: ${pixData.qrcodeUrl}`);

Pagamento com Boleto

const payment = await sdk.createPayment({
  amount: 10000,
  currency: 'BRL',
  description: 'Compra na loja XYZ',
  paymentMethod: {
    type: 'boleto'
  },
  customer: {
    name: 'Fulano de Tal',
    email: '[email protected]',
    document: '12345678909',
    // Para boleto, o endereço é obrigatório
    address: {
      street: 'Rua Exemplo',
      number: '123',
      neighborhood: 'Centro',
      city: 'São Paulo',
      state: 'SP',
      zipCode: '01001000'
    }
  }
});

// Acessa os dados do boleto
const boletoData = payment.paymentMethod.boleto;
console.log(`URL do boleto: ${boletoData.url}`);
console.log(`Código de barras: ${boletoData.barcode}`);

Tokenização de Cartões

Por questões de segurança e conformidade com PCI DSS, o SDK utiliza tokens de cartão em vez de dados completos do cartão. Isso significa que:

1. Os dados do cartão (número, nome, data de expiração, CVV) são tokenizados no frontend usando a SDK da adquirente.
2. O token gerado é enviado para o backend.
3. O backend usa o token para processar o pagamento através deste SDK.

Benefícios da tokenização:

• Reduz o escopo de conformidade com PCI DSS
• Aumenta a segurança, pois os dados sensíveis do cartão não trafegam pelo seu sistema
• É o método recomendado por todas as adquirentes

Cada adquirente fornece sua própria SDK de frontend para tokenização:

• Mercado Pago: SDK JS
• Cielo: SDK JS
• PagSeguro: SDK JS
• Stone: SDK JS
• Iugu: SDK JS

Operações Suportadas

• createPayment: Cria um novo pagamento
• getPayment: Consulta um pagamento existente
• cancelPayment: Cancela um pagamento
• refundPayment: Reembolsa um pagamento
• capturePayment: Captura um pagamento pré-autorizado
• testConnection: Testa a conexão com a adquirente

Suporte a Assinaturas (em breve)

• createSubscription: Cria uma nova assinatura
• getSubscription: Consulta uma assinatura existente
• cancelSubscription: Cancela uma assinatura

Testes

O SDK inclui testes para verificar a funcionalidade de criação de pagamentos com diferentes métodos. Os testes estão localizados na pasta tests/.

Executando os Testes

Você pode executar os testes individualmente ou todos de uma vez:

# Executar todos os testes
npm run test:all

# Executar teste específico
npm run test:credit   # Teste de pagamento com cartão de crédito
npm run test:debit    # Teste de pagamento com cartão de débito
npm run test:boleto   # Teste de pagamento com boleto
npm run test:pix      # Teste de pagamento com PIX

# Executar script personalizado que executa todos os testes sequencialmente
npm run test:run-all

# Executar testes com cobertura de código
npm run test:coverage

Configuração dos Testes

Antes de executar os testes, você precisa configurar as credenciais de sandbox no arquivo tests/setup.ts. Consulte o arquivo tests/README.md para mais detalhes sobre a configuração e execução dos testes.

Cobertura de Código

O SDK inclui configuração para gerar relatórios de cobertura de código. Para executar os testes com cobertura:

npm run test:coverage

Isso gerará um relatório de cobertura na pasta coverage/. Você pode abrir o arquivo coverage/lcov-report/index.html no navegador para visualizar o relatório detalhado.

Exemplos Completos

O SDK inclui exemplos completos de uso na pasta examples/:

• examples/credit-card-payment.ts: Exemplo de pagamento com cartão de crédito
• examples/debit-card-payment.ts: Exemplo de pagamento com cartão de débito
• examples/boleto-payment.ts: Exemplo de pagamento com boleto
• examples/pix-payment.ts: Exemplo de pagamento com PIX

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.

Licença

MIT