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
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
- Comprador inicia checkout
- Backend cria preferência com
marketplace_fee
- Mercado Pago processa pagamento
- Webhook confirma status
- 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
- Seller inicia cadastro
- Redirect para Stripe Connect
- Seller completa KYC
- Webhook
account.updated
- 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 |
3c49df55e4