AI导哈

支付网关集成服务

一个用于与阿尔及利亚SATIM支付网关系统集成的MCP服务器，提供处理CIB/Edhahabia卡支付的结构化接口，适用于电子商务平台和AI助手。

  • by zakblacki
  • JavaScript
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 zakblacki/Satim-Payment-Gateway-Integration

使用说明

显然，您应该已经创建了一个帐户，并正在从这里获取凭据：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

目录

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

安装

先决条件

  • Node.js 18+
  • npm或纱线

逐步设置

  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. 安装依赖项：
# 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 payment

2.客户付款

  • 客户在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 （字符串，必填）：成功重定向URL
  • failUrl （字符串，可选）：重定向URL失败
  • force_terminal_id （字符串，必填）：银行分配的终端ID
  • udf1 （字符串，必填）：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 （字符串，必填）：注册时的订单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é"
  }
}

退款订单

处理已完成订单的退款。

参数：

  • 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';

// 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等工具进行更轻松的测试。

故障排除

常见问题及解决方法

  1. “不能在模块外使用import语句”

    # Make sure package.json has "type": "module"
npm pkg set type=module

  2. “找不到模块”错误

    # Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

  3. TypeScript编译错误

    # Check tsconfig.json configuration
# Make sure all dependencies are installed
npm install --save-dev @types/node

  4. 服务器连接问题

    # 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服务器自动处理此转换。

错误处理

订单注册错误

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

确认错误

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

退款错误

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

例子

完成付款流程

// 1. Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "test_merchant",
  password: "test_password"
});

// 2. Register order
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. Redirect customer to order.formUrl
// Customer completes payment and returns

// 4. Confirm payment
const confirmation = await mcp.callTool("confirm_order", {
  orderId: order.orderId,
  language: "FR"
});

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

// 6. Handle result
if (validation.status === "ACCEPTED") {
  // Process successful payment
  console.log("Payment successful:", validation.displayMessage);
} else if (validation.status === "REJECTED") {
  // Handle rejection
  console.log("Payment rejected");
} else {
  // Handle error
  console.log("Payment error:", validation.displayMessage);
}

处理退款

// Full refund
const refund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 250.75,  // Full original amount
  language: "FR"
});

// Partial refund
const partialRefund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 100.00,  // Partial amount
  language: "FR"
});

安全考虑

凭证管理

  • 安全地存储凭据（环境变量、密钥库）
  • 对所有通信使用HTTPS
  • 为API端点实现正确的身份验证

订单号安全

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

数据验证

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

日志记录与监视

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

生产部署

环境配置

# Production endpoints
SATIM_BASE_URL=https://satim.dz/payment/rest

# Development/Testing endpoints  
SATIM_BASE_URL=https://test.satim.dz/payment/rest

健康检查

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

// Add to your server
app.get('/health/satim', async (req, res) => {
  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规范，并包括阿尔及利亚电子商务平台所需的所有集成点。

相关 MCP