SafraPay MCP Server

Servidor MCP (Model Context Protocol) para integração com a API SafraPay, permitindo que agentes de IA realizem operações completas de pagamento, gestão de clientes, recorrência e muito mais.

🚀 Versão 0.2.0 - Arquitetura Agrupada com Autenticação Automática

Esta versão implementa uma arquitetura agrupada onde 12 ferramentas cobrem 110+ endpoints da API SafraPay, ao invés de criar uma ferramenta por endpoint.

⚡ Autenticação Automática

O servidor gerencia a autenticação completamente de forma automática:

• ✅ Gera token automaticamente na primeira requisição
• ✅ Reautentica automaticamente quando o token expira (erro 401)
• ✅ Usa as credenciais configuradas via variáveis de ambiente
• ✅ Você NUNCA precisa se preocupar com autenticação!

Benefícios da Arquitetura Agrupada

• ✅ Escalável: Não há limite de ferramentas para gerenciar
• ✅ Organizada: Ferramentas agrupadas por contexto funcional
• ✅ Flexível: Agente IA monta as requisições baseado na documentação
• ✅ Completa: Acesso a toda a API SafraPay com documentação embarcada
• ✅ Automática: Autenticação e renovação de token transparentes

📦 Instalação

npm install
npm run build

⚙️ Configuração

Crie um arquivo .env na raiz do projeto:

# Ambiente: HML ou PROD
SAFRA_ENV=HML

# Credenciais (obtenha no portal SafraPay)
SAFRA_CLIENT_ID=seu-client-id
SAFRA_CLIENT_SECRET=seu-merchant-token

# Token (opcional - será gerado automaticamente)
SAFRA_ACCESS_TOKEN=

🔧 Configuração no Claude Code

Adicione ao arquivo de configuração do MCP:

{
  "mcpServers": {
    "safrapay": {
      "command": "node",
      "args": ["/caminho/para/banco-safra-mcp/dist/index.js"],
      "env": {
        "SAFRA_ENV": "HML",
        "SAFRA_CLIENT_SECRET": "seu-merchant-token"
      }
    }
  }
}

🛠️ Ferramentas Disponíveis

O servidor expõe 12 ferramentas agrupadas que cobrem toda a API SafraPay:

1. safrapay_authentication

Gestão de usuários SafraPay

• CRUD de usuários
• Listar merchants do usuário

IMPORTANTE: A autenticação de token é AUTOMÁTICA. Não é necessário chamar endpoints de autenticação manualmente.

2. safrapay_payments

Processamento de pagamentos completo

• Clientes (customers)
• Cartão de crédito/débito
• 3D Secure (3DS)
• PIX
• Boleto
• Consulta de BIN
• Produtos
• Planos de taxas

3. safrapay_charges

Gestão de cobranças

• Buscar cobrança
• Capturar pré-autorização
• Cancelar/estornar

4. safrapay_vault

Tokenização de cartões (Cartão Protegido)

• Salvar cartão
• Atualizar cartão
• Buscar cartões
• Cartão temporário
• Validação zero dollar

5. safrapay_recurrence

Planos e assinaturas recorrentes

• CRUD de planos
• CRUD de assinaturas
• Assinaturas em lote
• Relatórios

6. safrapay_payment_link

Links de pagamento (SmartCheckout)

• Criar link
• Listar links
• Detalhes e exclusão

7. safrapay_checkout

Sessões de checkout

• Checkout Redirect
• Checkout Lightbox
• Checkout Transparente

8. safrapay_split

Split de pagamentos

• Gestão de recebedores
• Configuração de split
• Extrato digital
• Saldo disponível

9. safrapay_accreditation

Credenciamento

• Gestão de merchants
• Sub-merchants
• Taxas e produtos
• Upload de documentos
• Reconciliação
• Adquirentes virtuais

10. safrapay_webhook

Webhooks para eventos

• Criar webhooks
• Listar webhooks
• Cancelar webhook

11. safrapay_chargeback

Gestão de disputas

• Resumo de disputas
• Detalhes de disputa
• Aceitar débito
• Representação secundária

12. safrapay_tef

Integração com PinPads

• Fluxo transacional completo
• Funções auxiliares

💡 Exemplos de Uso

Exemplo 1: Criar uma transação de crédito

Usuário: "Crie uma transação de crédito de R$ 100,00"

Agente IA usa: safrapay_payments
{
  "api": "GATEWAY",
  "method": "POST",
  "path": "/v2/charge/authorization",
  "body": {
    "charge": {
      "merchantChargeId": "ORDER-123",
      "transactions": [{
        "card": {
          "cardholderName": "JOAO SILVA",
          "cardNumber": "4111111111111111",
          "expirationMonth": 12,
          "expirationYear": 2025,
          "securityCode": "123"
        },
        "paymentType": 2,
        "amount": 10000,
        "installmentNumber": 1,
        "installmentType": 0,
        "autoCapture": true
      }],
      "source": 1
    }
  }
}

Exemplo 2: Criar cobrança PIX

Usuário: "Crie uma cobrança PIX de R$ 50,00"

Agente IA usa: safrapay_payments
{
  "api": "GATEWAY",
  "method": "POST",
  "path": "/v2/charge/pix",
  "body": {
    "charge": {
      "merchantChargeId": "PIX-456",
      "transactions": [{
        "amount": 5000,
        "paymentType": "Pix"
      }],
      "source": 1
    }
  }
}

Exemplo 3: Criar assinatura recorrente

Usuário: "Crie uma assinatura mensal de R$ 99,90"

Passo 1 - Criar plano (safrapay_recurrence):
{
  "api": "PORTAL",
  "method": "POST",
  "path": "/plan",
  "body": {
    "name": "Plano Premium",
    "amount": 9990,
    "interval": 3,
    "intervalCount": 1
  }
}

Passo 2 - Criar assinatura (safrapay_recurrence):
{
  "api": "GATEWAY",
  "method": "POST",
  "path": "/subscription",
  "body": {
    "planId": "plan-123",
    "customerId": "customer-456",
    "cardToken": "token-abc"
  }
}

📚 Documentação Completa

Consulte os arquivos na raiz do projeto:

• SAFRAPAY_API_MAPPING.md: Mapeamento completo de todas as rotas organizadas por grupo
• API_DOCUMENTATION.md: Documentação técnica detalhada com exemplos de request/response

🔑 Enumeradores Importantes

Status de Transação

• 1 - Pendente
• 2 - Autorizada
• 3 - Capturada
• 4 - Cancelada
• 5 - Negada
• 6 - Estornada

Tipos de Pagamento

• 2 - Crédito
• 3 - Débito
• 4 - Boleto
• 5 - PIX
• "Pix" - PIX (string)
• "Boleto" - Boleto (string)

Tipos de Parcelamento

• 0 - À vista
• 2 - Emissor (com juros)
• 3 - Lojista (sem juros)

Intervalos de Recorrência

• 1 - Diário
• 2 - Semanal
• 3 - Mensal
• 4 - Anual

Source (Origem)

• 1 - E-commerce/API
• 2 - Mobile
• 3 - Recorrência
• 4 - Telefone

🌐 Ambientes

Homologação (HML)

• Portal API: https://portal-api-hml.safrapay.com.br
• Gateway API: https://payment-hml.safrapay.com.br
• Reconciliation API: https://reconciliation-api-hml.safrapay.com.br

Produção (PROD)

• Portal API: https://portal-api.safrapay.com.br
• Gateway API: https://payment.safrapay.com.br
• Reconciliation API: https://reconciliation-api.safrapay.com.br

⚡ Desenvolvimento

# Compilar
npm run build

# Modo watch (desenvolvimento)
npm run dev

# Executar
npm start

🔒 Segurança

• NUNCA armazene dados de cartão completos
• Use tokenização sempre que possível
• Implemente validação zero dollar antes de cobranças recorrentes
• Utilize HTTPS em todos os endpoints
• Monitore transações suspeitas

🤝 Contribuindo

Este é um projeto em desenvolvimento ativo. Sugestões e melhorias são bem-vindas!

📄 Licença

ISC

👤 Autor

Marcelo Correa

Versão: 0.2.0 Última atualização: Janeiro 2026