萨提姆支付网关集成

Name: 萨提姆支付网关集成
Author: zakblacki

作者：zakblacki12 星标更新：2025-08-31

安装使用来源：spider==github.com

项目介绍

显然你需要已经创建并激活了一个账户来获取凭证：https://cibweb.dz/fr/login

Satim 支付网关集成

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

快速开始

# 克隆仓库
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

配置 package.json 以支持 ES 模块：

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 (字符串，必需)：成功重定向 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": "您的支付已被接受",
  "amount": 150050,
  "errorCode": "0",
  "orderStatus": 2,
  "approvalCode": "303004",
  "params": {
    "respCode": "00",
    "respCode_desc": "您的支付已被接受"
  }
}

refund_order

处理已完成订单的退款。

参数：

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

响应：

{
  "errorCode": 0
}

validate_payment_response

验证并解释支付响应。

参数：

response (对象，必需)：订单确认响应

响应：

{
  "status": "ACCEPTED",
  "displayMessage": "您的支付已被接受",
  "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 服务器已启动用于测试');

// 让它运行几秒钟然后退出
setTimeout(() => {
  server.kill();
  console.log('测试完成');
}, 5000);

运行：

node test-simple.js

方法 2：全面集成测试

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

npm run test

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

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

故障排除

常见问题及解决方案

“无法在模块外部使用 import 语句”

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

“模块未找到” 错误

# 重新安装依赖
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

用户界面需求

支付页面

显著显示最终金额（加粗、大字体）
包含 CAPTCHA 以防止自动化提交
在支付按钮上显示 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: "购买电子产品"
});

// 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("支付成功：", validation.displayMessage);
} else if (validation.status === "REJECTED") {
  // 处理拒绝
  console.log("支付被拒绝");
} else {
  // 处理错误
  console.log("支付错误：", 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 规范，并包含了阿尔及利亚电子商务平台所需的所有集成点。

萨提姆支付网关集成

项目介绍

显然你需要已经创建并激活了一个账户来获取凭证：https://cibweb.dz/fr/login

Satim 支付网关集成

快速开始

目录

安装

前提条件

分步设置

运行服务器

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

选项 2：编译并运行

选项 3：开发模式自动重载

配置

MCP 客户端配置

初始设置

环境变量

支付流程

1. 订单注册

2. 客户支付

3. 订单确认

4. 显示结果

工具

configure_credentials

register_order

confirm_order

refund_order

validate_payment_response

测试

方法 1：快速测试

方法 2：全面集成测试

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

故障排除

常见问题及解决方案

调试模式

集成需求

SSL 安全性

用户界面需求

支付页面

成功页面显示

成功页面操作

拒绝页面

金额处理

错误处理

订单注册错误

确认错误

退款错误

示例

完整支付流程

处理退款

安全考虑

凭证管理

订单编号安全性

数据验证

日志记录和监控

生产部署

环境配置

健康检查

支持和联系