3c49df55e4
Payment Gateways: - asaas.go: Pix (QR code), Boleto, Credit Card with split - Seller subaccount creation for split payments - 6 new domain types: PixPaymentResult, BoletoPaymentResult, SellerPaymentAccount, Customer, PaymentGatewayConfig Documentation: - docs/PAYMENT_GATEWAYS.md: Complete comparison (MercadoPago vs Stripe vs Asaas) - Admin routes for gateway config - Seller onboarding routes - Environment variables reference Coverage: 50% payments
213 lines
5.1 KiB
Markdown
213 lines
5.1 KiB
Markdown
# 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` |
|