Satim Payment Gateway Integration

🚀 萨蒂姆支付网关集成

这是一个模型上下文协议（MCP）服务器，用于与阿尔及利亚的 SATIM 支付网关系统集成。该服务器通过 SATIM - ePAY 平台为处理 CIB/Edhahabia 卡支付提供了一个结构化接口。此软件包使 Cursor、Claude 和 Copilot 等 AI 助手能够通过标准化接口直接访问你的账户数据。

点击查看更多

更多详情： https://code2tutorial.com/tutorial/6b3a062c - 3a34 - 4716 - 830e - 8793a5378bcc/index.md

🚀 快速开始

# 克隆仓库
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

# 安装依赖
npm install

# 运行服务器
npx tsx satim-mcp-server.ts
或
npm run dev

# 演示
启动 index.html

📚 目录

1. 安装
2. 配置
3. 支付流程
4. 工具
5. 测试
6. 集成要求
7. 错误处理
8. 示例
9. 安全考虑

📦 安装

前提条件

• Node.js 18+
• npm 或 yarn

逐步设置

1. 克隆并进入项目目录：

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

2. 初始化项目（如果 package.json 不存在）：

npm init -y

3. 为 ES 模块配置 package.json：

npm pkg set type=module

4. 安装依赖：

# 核心依赖
npm install @modelcontextprotocol/sdk axios

# 开发依赖
npm install --save-dev typescript @types/node tsx

运行服务器

选项 1：使用 tsx 直接执行（推荐用于开发）

npx tsx satim-mcp-server.ts

选项 2：编译并运行

# 编译 TypeScript
npm run build

# 运行编译后的 JavaScript
npm start

选项 3：使用自动重新加载的开发模式

npm run dev

⚙️ 配置

MCP 客户端配置

要将此服务器与 MCP 客户端（如 Claude Desktop）一起使用，请在你的配置中添加以下内容：

{
  "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"
      }
    }
  }
}

初始设置

在使用任何支付工具之前，请配置你的 SATIM 凭证：

// 配置凭证
await mcp.callTool("configure_credentials", {
  userName: "your_merchant_username",
  password: "your_merchant_password"
});

环境变量

在生产环境中，考虑使用环境变量：

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  # 生产环境使用 https://satim.dz/payment/rest

💸 支付流程

完整的支付过程遵循以下步骤：

1. 订单注册

const registrationResult = await mcp.callTool("register_order", {
  orderNumber: "ORDER_001_2024",
  amountInDA: 1500.50,  // 阿尔及利亚第纳尔金额
  returnUrl: "https://yoursite.com/payment/success",
  failUrl: "https://yoursite.com/payment/failure",
  force_terminal_id: "E005005097",
  udf1: "merchant_ref_123",
  language: "FR"
});

// 响应包含 orderId 和 formUrl
// 将客户重定向到 formUrl 进行支付

2. 客户支付

• 客户在 SATIM 表单上填写 CIB/Edhahabia 卡详细信息
• 客户被重定向回你的 returnUrl/failUrl

3. 订单确认

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

// 验证响应
const validation = await mcp.callTool("validate_payment_response", {
  response: confirmResult
});

4. 显示结果

根据验证结果，向客户显示适当的消息。

🛠️ 工具

configure_credentials

配置 SATIM 网关凭证。

参数：

• userName（字符串，必需）：商家登录名
• password（字符串，必需）：商家密码

register_order

注册新的支付订单。

参数：

• orderNumber（字符串，必需）：唯一订单标识符
• amountInDA（数字，必需）：阿尔及利亚第纳尔金额（最小值：50 DA）
• returnUrl（字符串，必需）：成功重定向 URL
• failUrl（字符串，可选）：失败重定向 URL
• force_terminal_id（字符串，必需）：银行分配的终端 ID
• udf1（字符串，必需）：SATIM 特定参数
• currency（字符串，可选）：货币代码（默认："012" 表示 DZD）
• language（字符串，可选）：界面语言（"AR"、"FR"、"EN"）
• description（字符串，可选）：订单描述
• udf2 - udf5（字符串，可选）：附加参数

响应：

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

confirm_order

在支付尝试后确认订单状态。

参数：

• orderId（字符串，必需）：注册时的订单 ID
• language（字符串，可选）：响应语言

响应：

{
  "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

处理已完成订单的退款。

参数：

• orderId（字符串，必需）：要退款的订单 ID
• amountInDA（数字，必需）：退款金额（单位：DA）
• currency（字符串，可选）：货币代码
• language（字符串，可选）：响应语言

响应：

{
  "errorCode": 0
}

validate_payment_response

验证并解释支付响应。

参数：

• response（对象，必需）：订单确认响应

响应：

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

🧪 测试

方法 1：快速测试

创建一个简单的测试文件 test - simple.js：

import { spawn } from 'child_process';

// 启动 MCP 服务器
const server = spawn('npx', ['tsx', 'satim-mcp-server.ts'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

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

// 让它运行几秒钟后退出
setTimeout(() => {
  server.kill();
  console.log('Test completed');
}, 5000);

使用以下命令运行：

node test-simple.js

方法 2：完整集成测试

按照文档中的示例创建 test - client.ts，然后运行：

npm run test

方法 3：用于 API 测试的 HTTP 包装器

使用文档中提供的 HTTP 包装器示例创建 REST API 端点，以便使用 Postman 或 curl 等工具进行更轻松的测试。

🐞 故障排除

常见问题及解决方案

1. “Cannot use import statement outside a module”

   # 确保 package.json 中有 "type": "module"
   npm pkg set type=module
   

2. “Module not found” 错误

   # 重新安装依赖
   rm -rf node_modules package-lock.json
   npm install
   

3. TypeScript 编译错误

   # 检查 tsconfig.json 配置
   # 确保所有依赖都已安装
   npm install --save-dev @types/node
   

4. 服务器连接问题

   # 检查服务器是否正在运行
   ps aux | grep tsx
   
   # 检查端口冲突
   lsof -i :3000  # 如果使用 HTTP 包装器
   

调试模式

启用调试日志记录：

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

🛠️ 集成要求

SSL 安全

• 必需：你的网站必须有 SSL 证书
• 所有 API 调用必须使用 HTTPS

用户界面要求

支付页面

• 显著显示最终金额（加粗、更大字体）
• 包含验证码以防止自动提交
• 在支付按钮上显示 CIB 标志
• 显示条款和条件并要求客户确认
• 在独立浏览器窗口中重定向到 SATIM 页面

成功页面显示

对于已接受的支付，显示：

• 交易消息 (respCode_desc)
• 交易 ID (orderId)
• 订单号 (orderNumber)
• 授权码 (approvalCode)
• 交易日期/时间
• 支付金额及货币
• 支付方式（CIB/Edhahabia）
• SATIM 联系电话：3020 3020

成功页面操作

• 打印收据选项
• 下载 PDF 收据
• 通过电子邮件将 PDF 收据发送给第三方

拒绝页面

• 以三种语言显示拒绝消息
• 显示 SATIM 联系信息

金额处理

发送到 SATIM 时，金额必须乘以 100：

• 50.00 DA → 发送 5000
• 806.50 DA → 发送 80650

MCP 服务器会自动处理此转换。

⚠️ 错误处理

订单注册错误

• 凭证无效
• 订单号重复
• 金额无效（< 50 DA）
• 缺少必需参数

确认错误

退款错误

💻 使用示例

完整支付流程

// 1. 配置凭证
await mcp.callTool("configure_credentials", {
  userName: "test_merchant",
  password: "test_password"
});

// 2. 注册订单
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. 将客户重定向到 order.formUrl
// 客户完成支付并返回

// 4. 确认支付
const confirmation = await mcp.callTool("confirm_order", {
  orderId: order.orderId,
  language: "FR"
});

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

// 6. 处理结果
if (validation.status === "ACCEPTED") {
  // 处理成功支付
  console.log("Payment successful:", validation.displayMessage);
} else if (validation.status === "REJECTED") {
  // 处理拒绝
  console.log("Payment rejected");
} else {
  // 处理错误
  console.log("Payment error:", validation.displayMessage);
}

处理退款

// 全额退款
const refund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 250.75,  // 原始全额
  language: "FR"
});

// 部分退款
const partialRefund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 100.00,  // 部分金额
  language: "FR"
});

🔒 安全考虑

凭证管理

• 安全存储凭证（环境变量、密钥库）
• 所有通信使用 HTTPS
• 为你的 API 端点实施适当的身份验证

订单号安全

• 使用唯一、非顺序的订单号
• 包含时间戳或随机元素
• 在确认前验证订单所有权

数据验证

• 始终在服务器端验证金额
• 在处理确认之前验证订单状态
• 为退款操作实施幂等性

日志记录和监控

• 记录所有支付交易
• 监控可疑活动
• 为 API 调用实施速率限制

🚀 生产部署

环境配置

# 生产端点
SATIM_BASE_URL=https://satim.dz/payment/rest

# 开发/测试端点  
SATIM_BASE_URL=https://test.satim.dz/payment/rest

健康检查

实施健康检查端点以监控网关连接性：

// 添加到你的服务器
app.get('/health/satim', async (req, res) => {
  try {
    // 测试与 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 });
  }
});

📞 支持与联系

• SATIM 支持：3020 3020（免费）
• 技术问题：联系你的集成专家
• 文档：参考 SATIM 官方集成指南

此 MCP 服务器实现遵循 SATIM 的官方 API 规范，包含了阿尔及利亚电子商务平台所需的所有集成点。