Pular para o conteúdo
CrazyStackCrazyStack início
Começar
Node.js + TypeScript

Gateway de pagamento Node.js com PIX e cartão

Integração completa de PIX e Cartão de Crédito com Woovi, Stripe e Pagar.me usando Padrão Adapter

Por que isso é importante

Como integrar PIX e cartão em Node.js/TypeScript sem acoplar um único PSP: crie uma interface PaymentGateway (Adapter), implemente Woovi/OpenPix, Stripe e Pagar.me, e trate webhook com HMAC + idempotência. Trocar PSP vira checklist — não rewrite do SaaS.

Leitura relacionada: Curso Node.js · Webhook Stripe · Abacate Pay · monetizar apps com IA.

payment-gateway.ts
export abstract class PaymentGateway {
abstract createCharge(data: any): Promise<any>;
abstract deleteCharge(id: string): Promise<any>;
abstract getCharge(id: string): Promise<any>;
}
Scroll
Padrão Adapter

Por que usar o Padrão Adapter para Gateway de Pagamento?

Use o padrão Adapter com TypeScript para uma interface unificada de PIX e cartão sobre Woovi, Stripe e Pagar.me. Sem Adapter, cada PSP vaza SDK e status codes no domínio do app — com Adapter, o SaaS fala só com createCharge/getCharge/webhooks normalizados.

Segurança e Tipagem

TypeScript garante tipagem estática e segurança do código em todas as implementações de gateway de pagamento, reduzindo erros em produção.

Flexibilidade e Escalabilidade

Interface comum permite trocar gateways de pagamento facilmente sem alterar o código principal da API Node.js.

Múltiplos Gateways de Pagamento

Suporte nativo para PIX, cartão de crédito e assinaturas em todos os gateways como Woovi, Stripe e Pagar.me.

Arquitetura

Estrutura do Projeto Node.js TypeScript

Organização modular com padrão Adapter para facilitar a manutenção e escalabilidade do código de gateway de pagamento

Estrutura de Diretórios

src/
├── contracts/
│ └── PaymentGateway.ts
├── adapters/
│ ├── WooviAdapter.ts
│ ├── StripeAdapter.ts
│ ├── PagarmeAdapter.ts
│ └── index.ts
└── config/
 └── env.ts

Fluxo de Processamento

1
Aplicação solicita pagamento via interface comum
2
Adapter converte para formato específico do gateway
3
Gateway processa e retorna resposta padronizada
Contrato Base
Interface comum que todos os gateways devem implementar
export abstract class PaymentGateway {
abstract createCharge(data: any): Promise<any>;
abstract deleteCharge(id: string): Promise<any>;
abstract getCharge(id: string): Promise<any>;
abstract createSubscription(data: any): Promise<any>;
abstract getSubscription(id: string): Promise<any>;
abstract createCustomer(data: any): Promise<any>;
abstract getCustomer(id: string): Promise<any>;
abstract getChargeByCustomer(data: any): Promise<any>;
}
Integrações

Gateways suportados: Woovi, Stripe e Pagar.me

Implemente múltiplos gateways de pagamento com uma única interface

Woovi
PIX Nativo
Gateway brasileiro especializado em PIX com API simples e eficiente
  • Cobrança PIX instantânea
  • Assinaturas recorrentes
  • Gestão de clientes
  • Webhooks em tempo real
Endpoint: api.openpix.com.br
Brasil
Stripe
Global
Plataforma global líder em pagamentos online com SDK robusto
  • Cartões internacionais
  • Checkout otimizado
  • Prevenção de fraudes
  • Dashboard avançado
SDK: stripe (oficial)
Internacional
Pagar.me
Brasil
Solução brasileira completa para pagamentos online e offline
  • PIX e cartões nacionais
  • Boleto bancário
  • Split de pagamentos
  • Antifraude integrado
API: REST com axios
Brasil
Implementação

Exemplo: Adapter Woovi em TypeScript

Veja como é simples implementar um gateway de pagamento usando o padrão Adapter

Woovi Adapter

Implementação do método createCharge para gerar cobranças PIX instantâneas.

Tratamento de erros robusto
Headers de autenticação
Suporte a cobranças existentes
Woovi Adapter - Criação de Cobrança PIX
src/adapters/WooviAdapter.ts
async createCharge(data: any): Promise<any> {
const { correlationID, value, comment } = data;
try {
const { data } = await axios.post(
https://api.openpix.com.br/api/v1/charge?return_existing=true,
{ correlationID, value, comment },
{
headers: { 
Authorization: this.apiKey,
content-type: application/json 
},
}
);
return data;
} catch (e: any) {
return e?.response?.data;
}
}
Bootcamp

CrazyStack Node.js

Bootcamp completo para desenvolvedores pleno/sênior que desejam dominar Node.js, TypeScript e padrões avançados de projeto.

Conteúdo Avançado

Design Patterns, TDD

Acesso Vitalício

Sem restrições

Projeto Real

Sistema completo

Aulas Divertidas

Personagens brasileiros

O que você vai aprender:

  • Clean Architecture e SOLID
  • Design Patterns avançados
  • TDD e testes de integração
  • Integração com gateways de pagamento
  • Autenticação e autorização
  • Fastify e MongoDB
  • Websockets e comunicação em tempo real
Preço
R$ 399,00
Acesso vitalício

Continue explorando

Quer ir além? Leia como criar API REST com Node.js, veja como criar um SaaS com IA, explore modelos de receita para apps, o curso de pagamentos crypto e os cursos da CrazyStack.

Webhooks: HMAC, assinatura e idempotência

Adapter unifica PIX e cartão; o que segura produção é o webhook. Nunca confie só no front — o PSP reenvia o mesmo evento.

  • Valide assinatura com o secret do provedor (HMAC/header). Stripe: stripe-signature; Mercado Pago: secret + docs de notificações; Woovi/OpenPix: assinatura/secret do painel OpenPix.
  • Responda 2xx rápido e processe de forma async se o trabalho for pesado — timeout gera retry.
  • Idempotency key: grave o event id / correlationID antes de marcar pedido pago. Reentrega = no-op se já pago.
  • Fonte da verdade: consulte a API do PSP (retrieve charge) se o payload vier ambíguo — “truth lands later”.

Confira a doc atual do PSP para o header exato. O padrão mental é o mesmo: verify → idempotent upsert → side effects uma vez.

Checklist: trocar de provedor (Woovi, Mercado Pago, Stripe)

Com PaymentGateway estável, trocar PSP é checklist — não rewrite:

  • Mapear status internos (created/pending/paid/expired/refunded/chargeback).
  • Reapontar webhooks + secrets por ambiente (sandbox → prod).
  • PIX nativo? Stripe no BR não substitui sozinho o fluxo PIX local.
  • Cartão: tokenização/PCI — nunca logar PAN; preferir SDK hospedado.
  • Moeda, parcelamento e prazo de liquidação alinhados ao contrato SaaS.
  • Testar chargeback/estorno no sandbox antes de migrar volume.
  • Feature flag por tenant/loja para rollback em minutos.

Falhas comuns: PIX, duplicata e chargeback

Modele estados explícitos: criado → aguardando PIX → pago | expirado | estornado | chargeback. O usuário e o backend precisam ver a mesma máquina de estados.

FalhaO que fazer
PIX expiradoUI: “gere novo QR”; backend não libera acesso; ignore webhook paid antigo se o charge foi rotacionado.
Cobrança duplicadaIdempotency key evita liberar duas assinaturas; se o PSP cobrou 2×, abra estorno — não “ignore”.
Pago no PSP, falha no DBJob de reconciliação consulta a API e fecha o gap.
ChargebackSuspenda o benefício; registre disputa; não apague histórico fiscal.

Fontes

Revisão em agosto de 2026. Este tutorial é padrão de engenharia (Adapter + webhooks) — não aconselhamento financeiro nem taxa contratual de PSP. Taxas %, liquidação PIX e chargeback mudam por contrato; valide no sandbox e na doc oficial antes de produção.

Stripe docs · OpenPix / Woovi developers · Pagar.me docs.

Perguntas frequentes

O que é um gateway de pagamento genérico em Node.js?

Camada com Adapter/interface comum sobre PSPs (PIX/cartão) — troca Woovi, Stripe ou Pagar.me sem reescrever o app.

Como integrar PIX e cartão no mesmo fluxo?

Com webhooks assinados e idempotência no servidor. Nunca marque pedido como pago só pelo front.

Por que usar Adapter pattern em pagamentos?

Cada PSP tem SDK e payload diferentes. Um contrato único (createCharge, webhook, etc.) isola o domínio do vendor lock-in.

Por onde começar o gateway?

Um PSP, um webhook com verificação de assinatura e estados de pedido claros (pendente/pago/expirado/falha).