Mastercard MCP

Mastercard Payment MCP Server 💳

🚀 Próximos Pasos | ⚡ Quick Start | 📊 Resumen del Proyecto | 🎯 Prompts Interactivos | 🎮 Modo Demo

MCP (Model Context Protocol) server completo para pagos end-to-end usando:

1. Mastercard MDES - Manual PAN Entry Tokenization
2. Fake PSP - Payment Service Provider simulado

🎯 Qué hace este MCP

Permite a un agente de IA procesar pagos completos de forma segura:

Tokenización (Mastercard MDES)

Convierte un PAN (Primary Account Number) en:

• DPAN (Network Token) - Token de red que sustituye al PAN
• Cryptogram EMV - Firma criptográfica de un solo uso
• ECI (Electronic Commerce Indicator)
• PAR (Payment Account Reference) - Identificador estable para pagos recurrentes

Procesamiento de pagos (Fake PSP)

Simula un PSP real (Payment Service Provider) con:

• Autorización de pagos con network tokens EMV
• Captura de fondos (settlement)
• Reembolsos (full/partial)
• Códigos de respuesta realistas (ISO 8583)
• Reglas de aprobación/declinación

Este MCP permite que agentes de IA cobren servicios sin necesidad de integrar Stripe, Adyen u otro PSP real.

✨ Características

Tokenización (MDES)

• ✅ Tokenización PAN → DPAN usando MDES
• ✅ Cifrado de campo (Field Level Encryption) con RSA + AES
• ✅ Autenticación OAuth 1.0a con firma RSA-SHA256
• ✅ Validación Luhn de tarjetas
• ✅ Verificación de tipo de tarjeta (solo Mastercard)
• ✅ Cumplimiento PCI-friendly (no almacena PANs)
• ✅ Modo sandbox para testing

PSP Fake

• ✅ Autorización de pagos con network tokens
• ✅ Captura de transacciones
• ✅ Reembolsos (full/partial)
• ✅ Códigos de respuesta ISO 8583
• ✅ Reglas de aprobación configurables
• ✅ Consulta de transacciones
• ✅ Tool all-in-one para agentes (pay_service)

🎯 Prompts Interactivos

• ✅ Prompt de Creación de Transacción (create_payment_transaction)

- Guía interactiva para solicitar todos los datos necesarios - Valida formato de tarjeta y datos de transacción - Indica claramente los errores - Usa automáticamente la herramienta pay_service

🔧 Requisitos previos

1. Registro en Mastercard Developer Portal

1. Crea una cuenta en https://developer.mastercard.com
2. Crea un nuevo proyecto y selecciona MDES Digital Enablement
3. Descarga las credenciales:

- Consumer Key - Signing Key (.p12 file) - Keystore Password - Encryption Certificate (.pem)

2. Dependencias

• Node.js >= 18
• TypeScript 5+

🚀 Instalación

# Clonar el repositorio
cd mastercard-mcp

# Instalar dependencias
npm install

# Crear directorio para certificados
mkdir certs

# Copiar tus credenciales de Mastercard
cp /ruta/a/tu/signing-key.p12 certs/
cp /ruta/a/tu/encryption-cert.pem certs/

# Configurar variables de entorno
cp .env.example .env

3. Configurar .env

MASTERCARD_CONSUMER_KEY=tu_consumer_key_aqui
MASTERCARD_KEYSTORE_PATH=./certs/tu-signing-key.p12
MASTERCARD_KEYSTORE_PASSWORD=tu_password
MASTERCARD_API_BASE_URL=https://sandbox.api.mastercard.com
MDES_ENCRYPTION_CERT_PATH=./certs/mdes-encryption-cert.pem

🔨 Build

npm run build

🎮 Uso

Como servidor MCP

Agregar a tu claude_desktop_config.json:

{
  "mcpServers": {
    "mastercard-tokenization": {
      "command": "node",
      "args": ["D:/programacion/bsv/mastercard-mcp/dist/index.js"],
      "env": {
        "MASTERCARD_CONSUMER_KEY": "tu_key",
        "MASTERCARD_KEYSTORE_PATH": "D:/programacion/bsv/mastercard-mcp/certs/signing.p12",
        "MASTERCARD_KEYSTORE_PASSWORD": "password",
        "MASTERCARD_API_BASE_URL": "https://sandbox.api.mastercard.com",
        "MDES_ENCRYPTION_CERT_PATH": "D:/programacion/bsv/mastercard-mcp/certs/encryption.pem"
      }
    }
  }
}

🎯 Prompts Interactivos

create_payment_transaction - Guía de Creación de Transacciones

Este prompt guía al agente de IA para que solicite interactivamente todos los datos necesarios para procesar un pago completo.

Características del Prompt:

• ✅ Argumentos interactivos - Solicita cada dato que falta
• ✅ Validación inteligente - Solo pide los datos que no tiene
• ✅ Progresivo - Puedes proporcionar datos en cualquier momento
• ✅ Flexible - Funciona con datos completos, parciales o sin datos

Argumentos que solicita:

1. Datos de la Tarjeta:

- cardNumber - Número de tarjeta (16 dígitos de Mastercard) - expiryMonth - Mes de expiración (MM, formato 01-12) - expiryYear - Año de expiración (YY, ejemplo: 25 para 2025) - cvv - CVV (3 dígitos)

1. Datos de la Transacción:

- amount - Monto a cobrar - currency - Moneda (código ISO 4217, ej: USD, EUR, MXN) - orderId - ID de orden único - description - Descripción del pago (opcional)

Cómo funciona:

1. Sin datos iniciales:

   Usuario: Quiero procesar un pago
   Claude: [Solicita todos los datos uno por uno]

1. Con algunos datos:

   Usuario: Procesa un pago de 99.99 USD para orden ABC-123
   Claude: [Solo solicita los datos de la tarjeta que faltan]

1. Con todos los datos:

   Usuario: [Proporciona todos los datos]
   Claude: [Valida y ejecuta pay_service inmediatamente]

Una vez que tenga todos los datos, el agente ejecutará automáticamente pay_service.

📖 Ver documentación completa de Prompts con ejemplos detallados de conversación y casos de uso.

Tools disponibles

Ver documentación completa del PSP fake en PSP-FAKE.md.

1. tokenize_card

Tokeniza una tarjeta y devuelve DPAN + cryptogram.

Input:

{
  "cardNumber": "5555555555554444",
  "expiryMonth": "12",
  "expiryYear": "28",
  "cvv": "123",
  "amount": 100.00,
  "currency": "USD"
}

Output:

{
  "success": true,
  "tokenization": {
    "networkToken": "555555******4444",
    "tokenExpiry": "12/28",
    "cryptogram": "AjF9a0kF991ASDFasdf...",
    "eci": "05",
    "paymentAccountReference": "V0010013456789012345678901234",
    "tokenReference": "DWSPMC000000000123456789",
    "status": "APPROVED"
  },
  "usage": {
    "description": "Use networkToken and cryptogram with your PSP",
    "example": {
      "stripe": {
        "card_number": "555555******4444",
        "cryptogram": "AjF9a0kF991ASDFasdf...",
        "exp_month": "12",
        "exp_year": "2028"
      }
    }
  }
}

2. validate_card

Valida formato de tarjeta antes de tokenizar.

Input:

{
  "cardNumber": "5555555555554444"
}

Output:

{
  "valid": true,
  "cardNumber": "************2345",
  "cardType": "Mastercard",
  "checks": {
    "luhn": "passed",
    "format": "valid",
    "issuer": "Mastercard"
  }
}

3. pay_service ⭐ (Recomendado)

Tool all-in-one que ejecuta el flujo completo: tokenización → autorización → captura.

Input:

{
  "cardNumber": "5555555555554444",
  "expiryMonth": "12",
  "expiryYear": "28",
  "cvv": "123",
  "amount": 49.99,
  "currency": "USD",
  "orderId": "ORD-001",
  "description": "Premium service payment"
}

Output (Success):

{
  "success": true,
  "payment": {
    "status": "COMPLETED",
    "orderId": "ORD-001",
    "amount": 49.99,
    "currency": "USD",
    "description": "Premium service payment",
    "pspReference": "PSP-1701234567890-ABCD123",
    "captureReference": "PSP-1701234567900-XYZ789",
    "authorizationCode": "A12345",
    "timestamp": "2025-11-29T20:01:00.000Z"
  },
  "tokenization": {
    "networkToken": "555555******4444",
    "tokenReference": "DWSPMC000000000123456789"
  }
}

4. psp_authorize

Autoriza un pago con network token (para flujos manuales).

5. psp_capture

Captura una autorización previa.

6. psp_refund

Reembolsa una transacción.

7. psp_get_transaction

Consulta detalles de una transacción.

Ver PSP-FAKE.md para documentación completa de todas las tools PSP.

🔐 Seguridad

✅ Cumplimiento PCI

• No almacena PANs - Los datos se cifran inmediatamente
• Field-level encryption - RSA-2048 + AES-256-CBC
• OAuth 1.0a - Firma RSA-SHA256 en cada request
• TLS 1.2+ - Todas las comunicaciones cifradas
• Validación Luhn - Previene errores de entrada

⚠️ Importante

• NUNCA commitees tus credenciales (.p12, .pem, .env) al repositorio
• Usa .gitignore para excluir certs/ y .env
• En producción, usa variables de entorno seguras (AWS Secrets Manager, Azure Key Vault, etc.)

🧪 Testing con Mastercard Sandbox

Tarjetas de Prueba Recomendadas

Tarjeta principal (Aprobación):

Número: 5555555555554444
Expiración: 12/28
CVV: 123

Tarjeta alternativa:

Número: 5105105105105100
Expiración: 12/28
CVV: 123

Escenarios de Prueba con el PSP Fake

Nota: El monto determina el comportamiento del PSP simulado:

• Montos < 5000: Transacción aprobada
• Montos ≥ 5500: Fondos insuficientes

URL Sandbox: https://sandbox.api.mastercard.com

🤖 Ejemplo de uso con agentes

User: Quiero pagar por el servicio premium ($49.99)

Agent: Perfecto, necesito los datos de tu tarjeta Mastercard:
- Número (16 dígitos)
- Fecha de expiración (MM/YY)
- CVV (3 dígitos)

User: 5555555555554444, 12/28, 123

Agent: [Llama a pay_service tool]

Agent: ✓ ¡Pago procesado exitosamente!
- Orden: ORD-20251129-001
- Monto: $49.99 USD
- Código de autorización: A8F3B2
- Referencia PSP: PSP-1701234567890-ABCD123

Tu servicio premium ya está activo. ¡Gracias por tu pago!

📚 Integración con PSPs reales

Si en el futuro quieres usar PSPs reales en lugar del fake PSP:

Stripe

const paymentMethod = await stripe.paymentMethods.create({
  type: 'card',
  card: {
    number: tokenization.networkToken,
    exp_month: tokenization.tokenExpiry.month,
    exp_year: '20' + tokenization.tokenExpiry.year,
    cryptogram: tokenization.cryptogram,
  },
});

Adyen

{
  "paymentMethod": {
    "type": "scheme",
    "encryptedCardNumber": tokenization.networkToken,
    "encryptedExpiryMonth": tokenization.tokenExpiry.month,
    "encryptedExpiryYear": tokenization.tokenExpiry.year,
    "networkTokenCryptogram": tokenization.cryptogram
  }
}

🗂 Estructura del proyecto

mastercard-mcp/
├── src/
│   ├── index.ts           # MCP Server principal con 7 tools
│   ├── config.ts          # Carga de configuración
│   ├── auth.ts            # OAuth 1.0a con RSA-SHA256
│   ├── encryption.ts      # Field-level encryption
│   ├── validation.ts      # Validación Luhn + Zod schemas
│   ├── mdes-client.ts     # Cliente MDES API
│   ├── types.ts           # TypeScript types
│   └── psp-fake/
│       ├── types.ts       # Types PSP
│       ├── validators.ts  # Validación PSP
│       ├── authorization-rules.ts  # Reglas de aprobación
│       ├── transaction-store.ts    # Storage in-memory
│       └── psp-client.ts  # Fake PSP client
├── certs/                 # Certificados (NO commitear)
├── .env                   # Variables de entorno (NO commitear)
├── package.json
├── tsconfig.json
├── README.md
├── SETUP.md               # Guía de setup paso a paso
└── PSP-FAKE.md           # Documentación del Fake PSP

🐛 Troubleshooting

Error: "Missing required environment variables"

Verifica que .env tiene todas las variables requeridas.

Error: "Keystore file not found"

Verifica que el path al .p12 es absoluto y correcto.

Error: "Mastercard API error: 401"

• Verifica tu Consumer Key
• Verifica que el .p12 no esté corrupto
• Verifica la password del keystore

Error: "Invalid card number (failed Luhn check)"

Usa una tarjeta de prueba válida de Mastercard sandbox.

📖 Referencias

• Mastercard MDES API Documentation
• Manual PAN Entry Tokenization
• MCP Protocol Specification

📖 Documentación completa

• QUICK-START.md - Inicio en 5 minutos ⚡
• SETUP.md - Guía de configuración paso a paso
• PSP-FAKE.md - Documentación del PSP fake
• EXAMPLES.md - Ejemplos completos de uso
• ARCHITECTURE.md - Arquitectura técnica detallada

📄 Licencia

MIT

🤝 Contribuciones

Pull requests son bienvenidos. Para cambios mayores, abre un issue primero.

Generado con Claude Code 🤖