🚀 萨蒂姆支付网关集成
这是一个模型上下文协议（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
📚 目录
- 安装
- 配置
- 支付流程
- 工具
- 测试
- 集成要求
- 错误处理
- 示例
- 安全考虑
📦 安装
前提条件
- Node.js 18+
- npm 或 yarn
逐步设置
- 克隆并进入项目目录：
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration
- 初始化项目（如果 package.json 不存在）：
npm init -y
- 为 ES 模块配置 package.json：
npm pkg set type=module
- 安装依赖：
# 核心依赖
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（字符串，必需）：成功重定向 URLfailUrl（字符串，可选）：失败重定向 URLforce_terminal_id（字符串，必需）：银行分配的终端 IDudf1（字符串，必需）：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（字符串，必需）：注册时的订单 IDlanguage（字符串，可选）：响应语言
响应：
{
"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（字符串，必需）：要退款的订单 IDamountInDA（数字，必需）：退款金额（单位：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 等工具进行更轻松的测试。
🐞 故障排除
常见问题及解决方案
-
“Cannot use import statement outside a module”
# 确保 package.json 中有 "type": "module" npm pkg set type=module -
“Module not found” 错误
# 重新安装依赖 rm -rf node_modules package-lock.json npm install -
TypeScript 编译错误
# 检查 tsconfig.json 配置 # 确保所有依赖都已安装 npm install --save-dev @types/node -
服务器连接问题
# 检查服务器是否正在运行 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 规范，包含了阿尔及利亚电子商务平台所需的所有集成点。