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

## 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
```env
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
```env
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
```env
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

```env
# 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` |