rede5/saveinmed
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
saveinmed/docs/PAYMENT_GATEWAYS.md
Tiago Yamamoto 78c7839e60 docs: add status sections to markdown files
2026-01-08 14:28:34 -03:00

5.3 KiB
Raw Blame History

Payment Gateways para Marketplace - Documentação Técnica

Status (pronto x faltando)

Pronto

  • Conteúdo descrito neste documento.

Faltando

  • Confirmar no código o estado real das funcionalidades e atualizar esta seção conforme necessário.

Visão Geral

SaveInMed suporta 4 gateways de pagamento para operações de marketplace com split automático de comissões.

Gateways Suportados

Gateway País Split Pix Cartão Boleto
Mercado Pago Brasil ✅ ✅ ✅ ✅
Stripe Global ✅ ❌ ✅ ❌
Asaas Brasil ✅ ✅ ✅ ✅
Mock Dev ✅ ✅ ✅ ✅

Arquitetura

                     ┌─────────────────┐
                     │  PaymentGateway │ (interface)
                     │    Interface    │
                     └────────┬────────┘
          ┌──────────────┬────┴─────┬──────────────┐
          ▼              ▼          ▼              ▼
    ┌───────────┐  ┌───────────┐ ┌───────────┐ ┌───────────┐
    │ MercadoPago│  │   Stripe  │ │   Asaas   │ │    Mock   │
    └───────────┘  └───────────┘ └───────────┘ └───────────┘

1. Mercado Pago

Credenciais Necessárias

MERCADOPAGO_ACCESS_TOKEN=APP_USR-xxxx
MERCADOPAGO_PUBLIC_KEY=APP_USR-xxxx
MERCADOPAGO_CLIENT_ID=xxxx
MERCADOPAGO_CLIENT_SECRET=xxxx
MERCADOPAGO_WEBHOOK_SECRET=xxxx

Split de Pagamento

  • Modelo: Marketplace com Application Fee
  • Comissão: Configurável (default 12%)
  • Liberação: Após confirmação de entrega

Fluxo

  1. Comprador inicia checkout
  2. Backend cria preferência com marketplace_fee
  3. Mercado Pago processa pagamento
  4. Webhook confirma status
  5. Split automático: Seller (88%) / Marketplace (12%)

2. Stripe

Credenciais Necessárias

STRIPE_SECRET_KEY=sk_live_xxxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxx
STRIPE_CONNECT_CLIENT_ID=ca_xxxx

Stripe Connect (Split)

  • Modelo: Standard Connect ou Express
  • Comissão: Application Fee
  • Onboarding: OAuth ou Hosted Onboarding

Fluxo Seller Onboarding

  1. Seller inicia cadastro
  2. Redirect para Stripe Connect
  3. Seller completa KYC
  4. Webhook account.updated
  5. Seller habilitado para receber

3. Asaas

Credenciais Necessárias

ASAAS_API_KEY=aact_xxxx
ASAAS_WALLET_ID=xxxx
ASAAS_WEBHOOK_TOKEN=xxxx
ASAAS_ENVIRONMENT=production|sandbox

Split de Pagamento

  • Modelo: Subcontas ou Split por cobrança
  • Comissão: Percentual fixo
  • Métodos: Pix, Boleto, Cartão

Vantagens

  • Gateway 100% brasileiro
  • Pix instantâneo
  • Boleto com baixo custo
  • Split nativo

4. Mock Gateway

Uso

  • Ambiente de desenvolvimento
  • Testes automatizados
  • CI/CD pipelines

Comportamento

  • Auto-aprovação de pagamentos
  • Simulação de refunds
  • Sem chamadas externas

Rotas de Configuração

Admin (SaaS Interno)

GET    /api/v1/admin/payment-gateways
       → Lista gateways configurados

PUT    /api/v1/admin/payment-gateways/:provider
       → Atualiza credenciais (encriptadas)

POST   /api/v1/admin/payment-gateways/:provider/test
       → Testa conectividade

DELETE /api/v1/admin/payment-gateways/:provider
       → Desativa gateway

Seller (Configuração Individual)

GET    /api/v1/sellers/:id/payment-config
       → Configuração atual do seller

PUT    /api/v1/sellers/:id/payment-config
       → Atualiza conta (Stripe Connect ID, etc)

POST   /api/v1/sellers/:id/onboarding
       → Inicia onboarding no gateway

Comparativo para Decisão

Critério Mercado Pago Stripe Asaas
Taxa Pix 0.99% ❌ N/A 0.49%
Taxa Cartão 4.99% 3.99% + 0.50 2.99%
Taxa Boleto R$ 3,99 ❌ N/A R$ 1,99
Split Nativo Connect Nativo
KYC Seller Simples Detalhado Simples
Webhook ✅ ✅ ✅
Sandbox ✅ ✅ ✅
Suporte BR ✅ Limitado ✅

Recomendação

Cenário Gateway Recomendado
Foco em Pix Asaas
Internacional Stripe
Maior conversão BR Mercado Pago
Menor taxa Asaas
Melhor experiência Stripe

Variáveis de Ambiente

# Gateway Ativo
ACTIVE_PAYMENT_GATEWAY=mercadopago|stripe|asaas|mock

# Taxa invisível do marketplace
BUYER_FEE_RATE=0.12

# Mercado Pago
MERCADOPAGO_ACCESS_TOKEN=
MERCADOPAGO_PUBLIC_KEY=
MERCADOPAGO_WEBHOOK_SECRET=

# Stripe
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=
STRIPE_CONNECT_CLIENT_ID=

# Asaas
ASAAS_API_KEY=
ASAAS_WALLET_ID=
ASAAS_WEBHOOK_TOKEN=
ASAAS_ENVIRONMENT=sandbox

Webhook Endpoints

Gateway Endpoint
Mercado Pago POST /webhooks/mercadopago
Stripe POST /webhooks/stripe
Asaas POST /webhooks/asaas