Entendendo o módulo de Pagamentos

Nosso Boilerplate SaaS traz um ecossistema nativo de assinaturas e faturamentos sob o módulo billing.

No entanto, o diferencial deste sistema é O Padrão Gateway (Multi-Provedor): nós permitimos que o seu sistema trabalhe não apenas com um gatilho de cobrança (ex: Pagar via Stripe), mas funcione como um hub de pagamentos agnóstico — permitindo instanciar PIX e Cartões com fallback inteligente.

Tudo isso encontra-se implementado em apps/api/src/lib/payments.

Como funciona na prática

Múltiplos gateways vêm conectados e pré-configurados:

• Asaas (Cartão e PIX)
• Abacate Pay (PIX)
• Woovi (PIX)
• PagueDev (PIX)

A principal classe orquestradora aqui chama-se PaymentGateway. Seu propósito é priorizar quem debita.

1. Fallback Automático: Se o provedor Asaas (Sua 1ª prioridade de PIX) falhar devido a instabilidade, nosso SDK instantaneamente passa para o Woovi na mesma requisição, permitindo sempre processar os pedidos dos seus clientes com 100% de uptime do módulo local.
2. Métodos Independentes: createPayment(), transferPix(), getPayment() são métodos agnósticos. Independentemente da plataforma escolhida para pagar, o retorno de sucesso e os webhooks estarão contidos em classes que validam na mesma interface de ProviderConfig.

A Estrutura do Código

1. payment.port.ts: Traz a padronização e os tipos base TCreatePaymentRequest.
2. payment.ts: O coração do Gateway; mantém a lista de pixProviders, cardProviders e regras de fallback e timeout com base nas suas chaves .env.
3. providers/: Implementações de cada Gateway isoladas.

✅ Em resumo: Para você, a lógica de faturamento complexa já está toda finalizada. Os boletos, assinaturas SaaS e os callbacks são gerenciados pelo billing.controller. Sua única função é definir as chaves de PIX ou cartão de crédito nos guias desta seção!