Gateway de Pagamento em Node.js

Gateway de Pagamento em Node.js: Criando uma Estrutura Genérica

Este artigo explica como implementar um gateway de pagamento genérico em Node.js, seguindo o padrão de arquitetura Clean Vertical Slice. O passo a passo aborda desde a geração das camadas necessárias do projeto até a integração de sistemas de pagamento por meio do padrão Adapter. O objetivo é viabilizar uma estrutura escalável, de fácil manutenção e preparada para expansão futura, especialmente útil para equipes que desejam suportar múltiplos provedores de pagamento (como PIX, cartão de crédito, entre outros) sem acoplamento excessivo

Source video

O que é um gateway de pagamento genérico?

Um gateway de pagamento genérico é uma implementação que possibilita a integração de diferentes métodos e provedores de pagamento por meio de uma única interface ou fluxo. Assim, é possível adicionar, remover ou alterar integrações de pagamento sem grandes refatorações, facilitando a adaptação do negócio a novas demandas e possibilitando testes e migrações de provedores.

Clean Vertical Slice: A Arquitetura escolhida

O padrão Clean Vertical Slice é uma abordagem arquitetural que divide a aplicação em "fatias" verticais, em vez de camadas horizontais tradicionais (como controller, service, repository). Cada fatia representa um conjunto de funcionalidades encapsuladas, desde a entrada da requisição até a persistência dos dados. Para gateways de pagamento, isso significa que há uma fatia dedicada à lógica de pagamento, diminuindo dependências cruzadas e isolando regras de negócio específicas.

Principais vantagens:

Isola contextos de negócio: funcionalidades referentes ao pagamento ficam separadas das demais.
Facilita testes: cada slice pode ser testada de forma independente.
Refatoração mais simples: mudanças para um gateway de pagamento não afetam outras partes do sistema.

Configuração inicial e geração de entidades

Para começar o projeto, é utilizado o comando:

yarn generate generateAll

Esse comando utiliza um gerador de arquivos que gera automaticamente todas as camadas essenciais para a entidade desejada — neste caso, "Customer". As camadas incluem rotas, domínios, controladores e serviços, todos estruturados conforme o padrão Clean Vertical Slice.

Por que gerar a entidade "Customer"?

A entidade "Customer" modela o cliente do sistema, ponto central no contexto de pagamentos. A partir dela, as demais funcionalidades relacionadas ao histórico de pagamentos, métodos utilizados e preferências podem ser desenvolvidas de forma coesa e isolada.

Organização do código: pasta "payment"

Manter um projeto organizado é essencial para garantir legibilidade e manutenção. Neste exemplo, tudo relacionado ao processamento de pagamentos é centralizado em uma pasta dedicada, chamada payment:

/project-root
│
├─ /customer
└─ /payment

Isso inclui:

Lógica de negócio para processamento de pagamentos;
Integração com provedores externos (exemplo: APIs do banco, PIX, gateways de cartão);
Testes unitários e de integração específicos de pagamento.

Com esta organização, novas funcionalidades como conciliação automática ou suporte a múltiplas moedas podem ser adicionadas sem bagunçar o restante do código.

Implementação do padrão Adapter para gateways de pagamento

O padrão Adapter é fundamental para desacoplar o código principal dos detalhes de implementação de cada provedor de pagamento. Ele permite integrar diversos sistemas de pagamento (por exemplo: sistemas bancários via PIX, adquirentes de cartão de crédito, soluções internacionais) utilizando uma interface genérica.

Como funciona o Adapter?

Define uma interface comum, como GatewayPagamento, com métodos como criarPagamento, consultarStatus, reembolsar etc.
Cada provedor é implementado como um "adapter" que traduz os métodos genéricos para a chamada específica da API do provedor.
O código principal utiliza apenas a interface genérica, sem se preocupar com detalhes de cada fornecedor.

Exemplo conceitual:

// Interface genérica
type GatewayPagamento = {
  criarPagamento: (dados: any) => Promise<any>,
  consultarStatus: (id: string) => Promise<any>
}

// Adapter do PIX
type PixAdapter = implements GatewayPagamento {
  criarPagamento(dados) { /* integração PIX */ },
  consultarStatus(id) { /* integração PIX */ },
}

// Adapter de Cartão
type CartaoAdapter = implements GatewayPagamento {
  criarPagamento(dados) { /* integração adquirente */ },
  consultarStatus(id) { /* integração adquirente */ },
}

Benefícios práticos dessa abordagem

Permite trocar ou adicionar novos métodos de pagamento sem reescrever o código principal.
Facilita testes simulando diferentes respostas dos provedores.
Reduz o risco de bugs ao incluir um novo provedor, pois a interface se mantém constante.

Considerações finais

Seguindo o fluxo apresentado — Clean Vertical Slice para organizar as funcionalidades e Adapter para integração flexível de provedores —, é possível manter o gateway de pagamento preparado para as necessidades do negócio e para o crescimento do sistema. Isso auxilia equipes que precisam suportar novos métodos como PIX e garante agilidade diante das constantes mudanças do mercado financeiro brasileiro e internacional.

Para uma demonstração completa e visual dessa construção, acesse o vídeo original: Gateway de pagamento no Nodejs de forma genérica usando PIX