Integrations - Gateway de Pagamento

Este diretório contém as integrações com provedores de pagamento externos.

Estrutura

Stripe (/stripe)

• Objetivo: Integração com Stripe para cartões internacionais

• Arquivos necessários:

  • stripe-client.js - Cliente principal do Stripe

  • stripe-webhooks.js - Processamento de webhooks

  • stripe-payments.js - Processamento de pagamentos

  • stripe-subscriptions.js - Gerenciamento de assinaturas

  • stripe-refunds.js - Processamento de reembolsos

  • stripe-utils.js - Utilitários e helpers

PayPal (/paypal)

• Objetivo: Integração com PayPal para pagamentos digitais

• Arquivos necessários:

  • paypal-client.js - Cliente principal do PayPal

  • paypal-express.js - PayPal Express Checkout

  • paypal-webhooks.js - Processamento de webhooks

  • paypal-subscriptions.js - Assinaturas recorrentes

  • paypal-disputes.js - Gerenciamento de disputas

  • paypal-utils.js - Utilitários e helpers

MercadoPago (/mercadopago)

• Objetivo: Integração com MercadoPago para mercado brasileiro

• Arquivos necessários:

  • mercadopago-client.js - Cliente principal do MercadoPago

  • mercadopago-pix.js - Integração com PIX

  • mercadopago-webhooks.js - Processamento de webhooks

  • mercadopago-installments.js - Parcelamentos

  • mercadopago-preferences.js - Criação de preferências

  • mercadopago-utils.js - Utilitários e helpers

Outros (/outros)

• Objetivo: Integrações com outros provedores

• Arquivos necessários:

  • pix-bacen.js - Integração direta com BACEN para PIX

  • boleto-bb.js - Boletos Banco do Brasil

  • cielo-api.js - Integração com Cielo

  • stone-api.js - Integração com Stone

  • pagseguro-api.js - Integração com PagSeguro

Padrão de Implementação

Interface Comum

Todas as integrações devem implementar uma interface comum:

class PaymentProvider {
  async processPayment(paymentData) {}
  async refundPayment(transactionId, amount) {}
  async getPaymentStatus(transactionId) {}
  async handleWebhook(webhookData) {}
  async validateWebhook(signature, payload) {}
}

Configuração por Provedor

Stripe

• Suporte a cartões internacionais

• Assinaturas recorrentes

• Connect para marketplace

• Radar para detecção de fraudes

PayPal

• PayPal Express Checkout

• PayPal Credit

• Braintree integration

• Vault para tokenização

MercadoPago

• Cartões nacionais e internacionais

• PIX instantâneo

• Boleto bancário

• Parcelamento sem juros

Funcionalidades por Provedor

Métodos de Pagamento Suportados

Stripe

• Cartões de crédito/débito

• Apple Pay / Google Pay

• SEPA Direct Debit

• Bank transfers

PayPal

• Conta PayPal

• Cartões via PayPal

• PayPal Credit

• Venmo (US)

MercadoPago

• Cartões de crédito/débito

• PIX

• Boleto bancário

• Conta MercadoPago

• Parcelamento

Recursos Avançados

Tokenização

• Armazenamento seguro de cartões

• One-click payments

• Compliance PCI DSS

• Rotação de tokens

Webhooks

• Notificações em tempo real

• Retry automático

• Validação de assinatura

• Idempotência

Antifraude

• Machine learning

• Regras customizáveis

• Score de risco

• Blacklist/whitelist

Tratamento de Erros

Códigos de Erro Padronizados

• INSUFFICIENT_FUNDS - Fundos insuficientes

• INVALID_CARD - Cartão inválido

• EXPIRED_CARD - Cartão expirado

• DECLINED - Transação recusada

• NETWORK_ERROR - Erro de rede

• PROVIDER_ERROR - Erro do provedor

Retry Strategy

• Retry automático para erros temporários

• Backoff exponencial

• Circuit breaker pattern

• Fallback para provedor secundário

Monitoramento e Logs

Métricas Importantes

• Taxa de sucesso por provedor

• Tempo de resposta médio

• Volume de transações

• Taxa de chargebacks

Logs de Auditoria

• Todas as requisições/respostas

• Webhooks recebidos

• Erros e exceções

• Tentativas de retry