显然，您应该已经创建了一个帐户，并正在从这里获取凭据：https://cibweb.dz/fr/login
Satim支付网关集成
用于与阿尔及利亚SATIM支付网关系统集成的模型上下文协议（MCP）服务器。该服务器提供了一个结构化接口，用于通过SATIM ePAY平台处理CIB/Edhahabia卡支付。该软件包使Cursor、Claude和Copilot等AI助手能够通过标准化的界面直接访问您的帐户数据。
更多详情： https://code2tutorial.com/tutorial/6b3a062c-3a34-4716-830e-8793a5378bcc/index.md
快速开始
# 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目录
安装
先决条件
- Node.js 18+
- npm或纱线
逐步设置
- 克隆并输入项目目录：
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- 安装依赖项：
# Core dependencies
npm install @modelcontextprotocol/sdk axios
# Development dependencies
npm install --save-dev typescript @types/node tsx运行服务器
选项1：使用tsx直接执行（建议用于开发）
npx tsx satim-mcp-server.ts选项2：编译并运行
# Compile TypeScript
npm run build
# Run compiled 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凭据：
// Configure credentials
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 # or https://satim.dz/payment/rest for production付款流程
完整的付款流程遵循以下步骤：
1.订单登记
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 payment2.客户付款
- 客户在SATIM表格上填写CIB/Edhahabia卡详细信息
- 客户被重定向回您的returnUrl/failUrl
3.订单确认
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.显示结果
根据验证结果，向客户显示适当的消息。
工具
配置证书
配置SATIM网关凭据。
参数：
userName（字符串，必填）：商户登录password（字符串，必填）：商户密码
注册_订购
注册新的付款订单。
参数：
orderNumber（字符串，必填）：唯一订单标识符amountInDA（数字，必填）：金额以阿尔及利亚第纳尔计（最低：50 DA）returnUrl（字符串，必填）：成功重定向URLfailUrl（字符串，可选）：重定向URL失败force_terminal_id（字符串，必填）：银行分配的终端IDudf1（字符串，必填）：SATIM特定参数currency（字符串，可选）：货币代码（DZD默认为“012”）language（字符串，可选）：接口语言（“AR”、“FR”、“EN”）description（字符串，可选）：订单描述udf2-udf5（字符串，可选）：其他参数
答复：
{
"orderId": "123456789AZERTYUIOPL",
"formUrl": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=123456789AZERTYUIOPL"
}确认订单
尝试付款后确认订单状态。
参数：
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é"
}
}退款订单
处理已完成订单的退款。
参数：
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';
// 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);运行方式：
node test-simple.js方法2：完全集成测试
创建 test-client.ts 按照文档中的示例，然后运行：
npm run test方法3：用于API测试的HTTP包装器
使用文档中提供的HTTP包装示例来创建RESTneneneba API端点，以便使用Postman或curl等工具进行更轻松的测试。
故障排除
常见问题及解决方法
- “不能在模块外使用import语句”
# Make sure package.json has "type": "module"
npm pkg set type=module- “找不到模块”错误
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install- TypeScript编译错误
# Check tsconfig.json configuration
# Make sure all dependencies are installed
npm install --save-dev @types/node- 服务器连接问题
# Check if server is running
ps aux | grep tsx
# Check for port conflicts
lsof -i :3000 # if using HTTP wrapper调试模式
启用调试日志记录：
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天→ 发送5000
- 806.50天→ 发送80650
MCP服务器自动处理此转换。
错误处理
订单注册错误
- 无效凭证
- 重复的订单号
- 无效金额（\ {
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 }); } });
## 支持和联系
- **SATIM支持**：3020 3020（免费电话）
- **技术问题**：联系您的集成专家
- **文档**：请参阅官方SATIM集成指南
______________________________________________________________________
*此MCP服务器实现遵循SATIM的官方API规范，并包括阿尔及利亚电子商务平台所需的所有集成点。*