Satim Payment Gateway Integration

🚀 SATIM決済ゲートウェイ統合

アルジェリアのSATIM決済ゲートウェイシステムと統合するためのモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは、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. package.jsonをESモジュール用に設定する:

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"
});

// レスポンスには注文IDとフォームURLが含まれます
// 顧客をフォームURLにリダイレクトして決済を行わせます

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ラッパーの例を使用して、Postmanやcurlなどのツールで簡単にテストできるREST APIエンドポイントを作成します。

🛠️ トラブルシューティング

一般的な問題と解決策

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を使用する必要があります

ユーザーインターフェイスの要件

決済ページ

• 最終金額を目立つように表示する（太字、大きなフォント）
• 自動送信を防止するためにCAPTCHAを含める
• 決済ボタンにCIBロゴを表示する
• 利用規約を表示し、顧客の承認を求める
• SATIMページに独立したブラウザウィンドウでリダイレクトする

成功ページの表示

決済が承認された場合、以下を表示します。

• トランザクションメッセージ (respCode_desc)
• トランザクションID (orderId)
• 注文番号 (orderNumber)
• 承認コード (approvalCode)
• トランザクション日時
• 通貨付きの決済金額
• 決済方法（CIB/Edhahabia）
• SATIMの連絡先: 3020 3020

成功ページのアクション

• レシートを印刷するオプション
• PDFレシートをダウンロードする
• PDFレシートを第三者にメールで送信する

拒否ページ

• 拒否メッセージを3言語で表示する
• 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. 顧客を注文の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仕様に従っており、アルジェリアの電子商取引プラットフォームに必要なすべての統合ポイントを含んでいます。