shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

Satim-Payment-Gateway-Integration

一个用于与阿尔及利亚SATIM支付网关系统集成的MCP服务器，提供处理CIB/Edhahabia卡支付的结构化接口，支持通过SATIM-ePAY平台进行支付处理。

article

README

🚀 萨蒂姆支付网关集成

这是一个模型上下文协议（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
  1. 初始化项目（如果 package.json 不存在）：
npm init -y
  1. 为 ES 模块配置 package.json：
npm pkg set type=module
  1. 安装依赖：
# 核心依赖
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）
  • 缺少必需参数

确认错误

| 错误代码 | 描述 | |------------|-------------| | 0 | 成功确认 | | 1 | 订单 ID 为空 | | 2 | 已确认 | | 3 | 访问被拒绝 | | 5 | 访问被拒绝 | | 6 | 未知订单 | | 7 | 系统错误 |

退款错误

| 错误代码 | 描述 | |------------|-------------| | 0 | 无系统错误 | | 5 | 需要更改密码 / 订单 ID 为空 | | 6 | 订单号错误 | | 7 | 支付状态错误 / 金额错误 / 系统错误 |

💻 使用示例

完整支付流程

// 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 规范，包含了阿尔及利亚电子商务平台所需的所有集成点。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client