Satim Payment Gateway Integration

🚀 薩蒂姆支付網關集成

這是一個模型上下文協議（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

2. 初始化項目（如果 package.json 不存在）：

npm init -y

3. 為 ES 模塊配置 package.json：

npm pkg set type=module

4. 安裝依賴：

# 核心依賴
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）
• 缺少必需參數

確認錯誤

退款錯誤

💻 使用示例

完整支付流程

// 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 規範，包含了阿爾及利亞電子商務平臺所需的所有集成點。