multi-acquirer-payment-controller

Controller Payment Multi Acquirer

Pacote de integração com múltiplas adquirentes de pagamento, permitindo processar pagamentos com diferentes provedores através de uma interface unificada.

Instalação

npm install multi-acquirer-payment-controller

Funcionalidades

• Integração com múltiplas adquirentes de pagamento
• Interface unificada para todas as operações
• Suporte a diferentes métodos de pagamento (cartão de crédito, boleto, PIX, etc.)
• Operações de pagamento, consulta e estorno
• Fácil extensão para adicionar novas adquirentes

Adquirentes Suportadas

• PagSeguro
• Mercado Pago (em breve)
• Outras adquirentes podem ser adicionadas facilmente

Uso Básico

Inicialização

import { PaymentController } from 'controller-payment-multi-acquirer';

// Cria o controlador com o provedor desejado
const paymentController = new PaymentController('pagseguro');

// Inicializa com as credenciais
await paymentController.initialize({
  email: '[e-mail]',
  token: 'seu-token-de-acesso'
}, 'sandbox'); // ou 'production'

Gerar Pagamento

const paymentResult = await paymentController.generatePayment({
  orderId: 'pedido-123',
  description: 'Compra na loja virtual',
  amount: 1000, // R$ 10,00
  customer: {
    name: 'José da Silva',
    email: '[e-mail]',
    documentNumber: '12345678909'
  },
  items: [
    {
      id: 'produto-1',
      name: 'Produto de Teste',
      quantity: 1,
      unitAmount: 1000
    }
  ],
  paymentMethod: {
    type: 'credit_card',
    installments: 1,
    card: {
      number: '4111111111111111',
      expirationMonth: 12,
      expirationYear: 2030,
      securityCode: '123',
      holderName: 'José da Silva'
    }
  }
});

console.log('Pagamento gerado:', paymentResult);

Consultar Pagamento

const paymentInfo = await paymentController.queryPayment('ID_DO_PAGAMENTO');
console.log('Informações do pagamento:', paymentInfo);

Estornar Pagamento

// Estorno total
const refundResult = await paymentController.refundPayment('ID_DO_PAGAMENTO');
console.log('Estorno realizado:', refundResult);

// Estorno parcial
const partialRefundResult = await paymentController.refundPayment('ID_DO_PAGAMENTO', 500); // R$ 5,00
console.log('Estorno parcial realizado:', partialRefundResult);

Trocar de Adquirente

// Altera para outro provedor
paymentController.changeProvider('mercadopago');

// Inicializa com as credenciais do novo provedor
await paymentController.initialize({
  accessToken: 'seu-access-token-do-mercado-pago'
}, 'sandbox');

Tratamento de Erros

import { PaymentError, ErrorCodes } from 'controller-payment-multi-acquirer';

try {
  const paymentResult = await paymentController.generatePayment({
    // dados do pagamento
  });
} catch (error) {
  if (error instanceof PaymentError) {
    console.error(`Erro de pagamento: ${error.message}`);
    console.error(`Código: ${error.code}`);
    console.error('Dados adicionais:', error.data);
    
    // Tratamento específico por código de erro
    if (error.code === ErrorCodes.PAYMENT_CREATION_ERROR) {
      // Lógica específica para erro de criação de pagamento
    }
  } else {
    console.error('Erro desconhecido:', error);
  }
}

Adicionando uma Nova Adquirente

Para adicionar uma nova adquirente, você precisa:

• Criar uma nova pasta em src/gateways com o nome da adquirente
• Implementar a interface PaymentGatewayInterface
• Adicionar a nova adquirente na factory PaymentGatewayFactory

Testes

O pacote inclui testes automatizados para todas as funcionalidades principais. Os testes estão localizados na pasta .tests e são organizados por funcionalidade:

• Teste de inicialização/conexão
• Teste de criação de pagamento
• Teste de consulta de pagamento
• Teste de estorno de pagamento

Executando os testes

Para executar todos os testes:

npm test

Para executar testes específicos:

# Teste de inicialização
npm run test:init

# Teste de criação de pagamento
npm run test:create

# Teste de consulta de pagamento
npm run test:query

# Teste de estorno de pagamento
npm run test:refund

# Executar todos os testes em sequência
npm run test:all

Para mais detalhes sobre os testes, consulte o README da pasta de testes.

Licença

MIT