Satim Payment Gateway Integration

Obviamente, ya deberías tener una cuenta creada y funcionando para obtener credenciales desde aquí: https://cibweb.dz/fr/login

Integración de la Pasarela de Pago Satim

Un servidor de Protocolo de Contexto de Modelo (MCP) para integrarse con el sistema de pasarela de pago SATIM en Argelia. El servidor proporciona una interfaz estructurada para procesar pagos con tarjetas CIB/Edhahabia a través de la plataforma SATIM-ePAY. Este paquete permite que asistentes de IA como Cursor, Claude y Copilot accedan directamente a los datos de tu cuenta mediante una interfaz estandarizada.

Inicio Rápido

# Clone the repository
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

# Install dependencies
npm install

# Run the server
npx tsx satim-mcp-server.ts
or
npm run dev

# Demo 
Launch index.html

Tabla de Contenidos

1. Instalación
2. Configuración
3. Flujo de Pago
4. Herramientas
5. Pruebas
6. Requisitos de Integración
7. Manejo de Errores
8. Ejemplos
9. Consideraciones de Seguridad

Instalación

Requisitos Previos

• Node.js 18+
• npm o yarn

Configuración Paso a Paso

1. Clona y entra al directorio del proyecto:

git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

2. Inicializa el proyecto (si package.json no existe):

npm init -y

3. Configura package.json para módulos ES:

npm pkg set type=module

4. Instala las dependencias:

# Core dependencies
npm install @modelcontextprotocol/sdk axios

# Development dependencies
npm install --save-dev typescript @types/node tsx

Ejecutar el Servidor

Opción 1: Ejecución directa con tsx (Recomendado para desarrollo)

npx tsx satim-mcp-server.ts

Opción 2: Compilar y ejecutar

# Compile TypeScript
npm run build

# Run compiled JavaScript
npm start

Opción 3: Modo desarrollo con recarga automática

npm run dev

Configuración

Configuración del Cliente MCP

Para usar este servidor con un cliente MCP (como Claude Desktop), añade a tu configuración:

{
  "mcpServers": {
      "satim-payment": {
       "command": "npx",
       "args": ["@devqxi/satim-payment-gateway-mcp"],
       "env": {
        "SATIM_USERNAME": "your_test_username",
        "SATIM_PASSWORD": "your_test_password",
        "NODE_ENV": "development"
      }
    }
  }
}

Configuración Inicial

Antes de usar cualquier herramienta de pago, configura tus credenciales SATIM:

// Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "your_merchant_username",
  password: "your_merchant_password"
});

Variables de Entorno

Para producción, considera usar variables de entorno:

SATIM_USERNAME=your_merchant_username
SATIM_PASSWORD=your_merchant_password
SATIM_TERMINAL_ID=your_terminal_id
SATIM_BASE_URL=https://test.satim.dz/payment/rest  # or https://satim.dz/payment/rest for production

Flujo de Pago

El proceso de pago completo sigue estos pasos:

1. Registro de Pedido

const registrationResult = await mcp.callTool("register_order", {
  orderNumber: "ORDER_001_2024",
  amountInDA: 1500.50,  // Amount in Algerian Dinars
  returnUrl: "https://yoursite.com/payment/success",
  failUrl: "https://yoursite.com/payment/failure",
  force_terminal_id: "E005005097",
  udf1: "merchant_ref_123",
  language: "FR"
});

// Response includes orderId and formUrl
// Redirect customer to formUrl for payment

2. Pago del Cliente

• El cliente completa los datos de su tarjeta CIB/Edhahabia en el formulario SATIM
• El cliente es redirigido de vuelta a tu returnUrl/failUrl

3. Confirmación del Pedido

const confirmResult = await mcp.callTool("confirm_order", {
  orderId: "received_order_id",
  language: "FR"
});

// Validate the response
const validation = await mcp.callTool("validate_payment_response", {
  response: confirmResult
});

4. Mostrar Resultados

Según los resultados de validación, muestra los mensajes apropiados a los clientes.

Herramientas

configure_credentials

Configura las credenciales de la pasarela SATIM.

Parámetros:

• userName (string, obligatorio): Inicio de sesión del comerciante
• password (string, obligatorio): Contraseña del comerciante

register_order

Registra un nuevo pedido de pago.

Parámetros:

• orderNumber (string, obligatorio): Identificador único del pedido
• amountInDA (number, obligatorio): Monto en Dinares Argelinos (mín: 50 DA)
• returnUrl (string, obligatorio): URL de redirección de éxito
• failUrl (string, opcional): URL de redirección de fallo
• force_terminal_id (string, obligatorio): ID de terminal asignado por el banco
• udf1 (string, obligatorio): Parámetro específico de SATIM
• currency (string, opcional): Código de moneda (por defecto: "012" para DZD)
• language (string, opcional): Idioma de la interfaz ("AR", "FR", "EN")
• description (string, opcional): Descripción del pedido
• udf2-udf5 (string, opcional): Parámetros adicionales

Respuesta:

{
  "orderId": "123456789AZERTYUIOPL",
  "formUrl": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=123456789AZERTYUIOPL"
}

confirm_order

Confirma el estado del pedido después del intento de pago.

Parámetros:

• orderId (string, obligatorio): ID del pedido del registro
• language (string, opcional): Idioma de la respuesta

Respuesta:

{
  "orderNumber": "ORDER_001_2024",
  "actionCode": 0,
  "actionCodeDescription": "Votre paiement a été accepté",
  "amount": 150050,
  "errorCode": "0",
  "orderStatus": 2,
  "approvalCode": "303004",
  "params": {
    "respCode": "00",
    "respCode_desc": "Votre paiement a été accepté"
  }
}

refund_order

Procesa un reembolso para un pedido completado.

Parámetros:

• orderId (string, obligatorio): ID del pedido a reembolsar
• amountInDA (number, obligatorio): Monto del reembolso en DA
• currency (string, opcional): Código de moneda
• language (string, opcional): Idioma de la respuesta

Respuesta:

{
  "errorCode": 0
}

validate_payment_response

Valida e interpreta la respuesta del pago.

Parámetros:

• response (object, obligatorio): Respuesta de confirmación del pedido

Respuesta:

{
  "status": "ACCEPTED",
  "displayMessage": "Votre paiement a été accepté",
  "shouldShowContactInfo": false,
  "contactNumber": "3020 3020"
}

Pruebas

Método 1: Prueba Rápida

Crea un archivo de prueba simple test-simple.js:

import { spawn } from 'child_process';

// Start the MCP server
const server = spawn('npx', ['tsx', 'satim-mcp-server.ts'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

console.log('SATIM MCP Server started for testing');

// Let it run for a few seconds then exit
setTimeout(() => {
  server.kill();
  console.log('Test completed');
}, 5000);

Ejecuta con:

node test-simple.js

Método 2: Prueba de Integración Completa

Crea test-client.ts siguiendo el ejemplo en la documentación, luego ejecuta:

npm run test

Método 3: Envoltorio HTTP para Pruebas de API

Usa el ejemplo de envoltorio HTTP proporcionado en la documentación para crear endpoints de API REST para pruebas más fáciles con herramientas como Postman o curl.

Solución de Problemas

Problemas Comunes y Soluciones

1. "Cannot use import statement outside a module"

   # Make sure package.json has "type": "module"
   npm pkg set type=module
   

2. Errores de "Module not found"

   # Reinstall dependencies
   rm -rf node_modules package-lock.json
   npm install
   

3. Errores de compilación de TypeScript

   # Check tsconfig.json configuration
   # Make sure all dependencies are installed
   npm install --save-dev @types/node
   

4. Problemas de conexión del servidor

   # Check if server is running
   ps aux | grep tsx
   
   # Check for port conflicts
   lsof -i :3000  # if using HTTP wrapper
   

Modo Depuración

Habilita el registro de depuración:

DEBUG=true npx tsx satim-mcp-server.ts

Requisitos de Integración

Seguridad SSL

• Obligatorio: Tu sitio web debe tener certificado SSL
• Todas las llamadas a la API deben usar HTTPS

Requisitos de Interfaz de Usuario

Página de Pago

• Mostrar el monto final de manera prominente (negrita, fuente más grande)
• Incluir CAPTCHA para prevenir envíos automatizados
• Mostrar el logotipo de CIB en el botón de pago
• Mostrar términos y condiciones con confirmación del cliente
• Redirigir a la página SATIM en una ventana de navegador independiente

Pantalla de Éxito

Para pagos aceptados, mostrar:

• Mensaje de transacción (respCode_desc)
• ID de transacción (orderId)
• Número de pedido (orderNumber)
• Código de autorización (approvalCode)
• Fecha/hora de la transacción
• Monto del pago con moneda
• Método de pago (CIB/Edhahabia)
• Contacto SATIM: 3020 3020

Acciones de la Pantalla de Éxito

• Opción de imprimir recibo
• Descargar recibo en PDF
• Enviar recibo en PDF por correo a un tercero

Página de Rechazo

• Mostrar mensaje de rechazo en tres idiomas
• Mostrar información de contacto de SATIM

Manejo de Montos

Los montos deben multiplicarse por 100 al enviarse a SATIM:

• 50.00 DA → enviar 5000
• 806.50 DA → enviar 80650

El servidor MCP maneja esta conversión automáticamente.

Manejo de Errores

Errores de Registro de Pedido

• Credenciales inválidas
• Número de pedido duplicado
• Monto inválido (< 50 DA)
• Parámetros obligatorios faltantes

Errores de Confirmación

Código de Error	Descripción
0	Confirmado exitosamente
1	ID de pedido vacío
2	Ya confirmado
3	Acceso denegado
5	Acceso denegado
6	Pedido desconocido
7	Error del sistema

Errores de Reembolso

Código de Error	Descripción
0	Sin error del sistema
5	Cambio de contraseña requerido / ID de pedido vacío
6	Número de pedido incorrecto
7	Error de estado del pago / Error de monto / Error del sistema

Ejemplos

Flujo de Pago Completo

// 1. Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "test_merchant",
  password: "test_password"
});

// 2. Register order
const order = await mcp.callTool("register_order", {
  orderNumber: `ORDER_${Date.now()}`,
  amountInDA: 250.75,
  returnUrl: "https://mystore.dz/payment/success",
  failUrl: "https://mystore.dz/payment/failure",
  force_terminal_id: "E005005097",
  udf1: "customer_ref_456",
  language: "FR",
  description: "Achat produit électronique"
});

// 3. Redirect customer to order.formUrl
// Customer completes payment and returns

// 4. Confirm payment
const confirmation = await mcp.callTool("confirm_order", {
  orderId: order.orderId,
  language: "FR"
});

// 5. Validate response
const validation = await mcp.callTool("validate_payment_response", {
  response: confirmation
});

// 6. Handle result
if (validation.status === "ACCEPTED") {
  // Process successful payment
  console.log("Payment successful:", validation.displayMessage);
} else if (validation.status === "REJECTED") {
  // Handle rejection
  console.log("Payment rejected");
} else {
  // Handle error
  console.log("Payment error:", validation.displayMessage);
}

Procesamiento de Reembolsos

// Full refund
const refund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 250.75,  // Full original amount
  language: "FR"
});

// Partial refund
const partialRefund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 100.00,  // Partial amount
  language: "FR"
});

Consideraciones de Seguridad

Gestión de Credenciales

• Almacena las credenciales de forma segura (variables de entorno, bóveda de claves)
• Usa HTTPS para todas las comunicaciones
• Implementa autenticación adecuada para tus endpoints de API

Seguridad del Número de Pedido

• Usa números de pedido únicos y no secuenciales
• Incluye marcas de tiempo o elementos aleatorios
• Valida la propiedad del pedido antes de la confirmación

Validación de Datos

• Siempre valida los montos en el lado del servidor
• Verifica el estado del pedido antes de procesar confirmaciones
• Implementa idempotencia para operaciones de reembolso

Registro y Monitoreo

• Registra todas las transacciones de pago
• Monitorea actividades sospechosas
• Implementa limitación de velocidad para llamadas a la API

Despliegue en Producción

Configuración del Entorno

# Production endpoints
SATIM_BASE_URL=https://satim.dz/payment/rest

# Development/Testing endpoints  
SATIM_BASE_URL=https://test.satim.dz/payment/rest

Verificaciones de Salud

Implementa endpoints de verificación de salud para monitorear la conectividad de la pasarela:

// Add to your server
app.get('/health/satim', async (req, res) => {
  try {
    // Test connection to SATIM
    const response = await axios.get(`${SATIM_BASE_URL}/health`);
    res.json({ status: 'healthy', satim: 'connected' });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: error.message });
  }
});

Soporte y Contacto

• Soporte SATIM: 3020 3020 (línea gratuita)
• Problemas Técnicos: Contacta a tu especialista de integración
• Documentación: Consulta las guías oficiales de integración de SATIM

---

Esta implementación del servidor MCP sigue las especificaciones oficiales de la API de SATIM e incluye todos los puntos de integración requeridos para plataformas de comercio electrónico argelinas.