Satim Payment Gateway Integration

A Model Context Protocol (MCP) server for integrating with the SATIM payment gateway system in Algeria. The server provides a structured interface for processing CIB/Edhahabia card payments through the SATIM-ePAY platform. This package enables AI assistants like Cursor, Claude, and Copilot to directly access your Razorpay account data through a standardized interface.

More details : https://code2tutorial.com/tutorial/6b3a062c-3a34-4716-830e-8793a5378bcc/index.md

Quick Start

# Clone the repository
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

# Install dependencies
npm install @modelcontextprotocol/sdk axios
npm install --save-dev typescript @types/node tsx

# Run the server
npx tsx satim-mcp-server.ts
or
npm run dev

# Demo 
Launch index.html

Installation

Prerequisites

Node.js 18+
npm or yarn

Step-by-Step Setup

Clone and enter the project directory:

git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

Initialize the project (if package.json doesn't exist):

npm init -y

Configure package.json for ES modules:

npm pkg set type=module

Install dependencies:

# Core dependencies
npm install @modelcontextprotocol/sdk axios

# Development dependencies
npm install --save-dev typescript @types/node tsx

Running the Server

Option 1: Direct execution with tsx (Recommended for development)

npx tsx satim-mcp-server.ts

Option 2: Compile and run

# Compile TypeScript
npm run build

# Run compiled JavaScript
npm start

Option 3: Development mode with auto-reload

npm run dev

Configuration

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add to your configuration:

{
  "mcpServers": {
    "satim-payment": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/path/to/your/satim-mcp-server.ts"
      ],
      "env": {
        "SATIM_USERNAME": "your_test_username",
        "SATIM_PASSWORD": "your_test_password",
        "NODE_ENV": "development"
      }
    }
  }
}

Initial Setup

Before using any payment tools, configure your SATIM credentials:

// Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "your_merchant_username",
  password: "your_merchant_password"
});

Environment Variables

For production, consider using environment variables:

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

Payment Flow

The complete payment process follows these steps:

1. Order Registration

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. Customer Payment

Customer fills CIB/Edhahabia card details on SATIM form
Customer is redirected back to your returnUrl/failUrl

3. Order Confirmation

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. Display Results

Based on validation results, display appropriate messages to customers.

Tools

configure_credentials

Configure SATIM gateway credentials.

Parameters:

userName (string, required): Merchant login
password (string, required): Merchant password

register_order

Parameters:

orderNumber (string, required): Unique order identifier
amountInDA (number, required): Amount in Algerian Dinars (min: 50 DA)
returnUrl (string, required): Success redirect URL
failUrl (string, optional): Failure redirect URL
force_terminal_id (string, required): Bank-assigned terminal ID
udf1 (string, required): SATIM-specific parameter
currency (string, optional): Currency code (default: "012" for DZD)
language (string, optional): Interface language ("AR", "FR", "EN")
description (string, optional): Order description
udf2-udf5 (string, optional): Additional parameters

Response:

{
  "orderId": "123456789AZERTYUIOPL",
  "formUrl": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=123456789AZERTYUIOPL"
}

confirm_order

Confirm order status after payment attempt.

Parameters:

orderId (string, required): Order ID from registration
language (string, optional): Response language

Response:

{
  "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

Process a refund for a completed order.

Parameters:

orderId (string, required): Order ID to refund
amountInDA (number, required): Refund amount in DA
currency (string, optional): Currency code
language (string, optional): Response language

Response:

{
  "errorCode": 0
}

validate_payment_response

Validate and interpret payment response.

Parameters:

response (object, required): Order confirmation response

Response:

{
  "status": "ACCEPTED",
  "displayMessage": "Votre paiement a été accepté",
  "shouldShowContactInfo": false,
  "contactNumber": "3020 3020"
}

Testing

Method 1: Quick Test

Create a simple test file 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);

Run with:

node test-simple.js

Method 2: Full Integration Test

Create test-client.ts following the example in the documentation, then run:

npm run test

Method 3: HTTP Wrapper for API Testing

Use the HTTP wrapper example provided in the documentation to create REST API endpoints for easier testing with tools like Postman or curl.

Troubleshooting

Common Issues and Solutions

"Cannot use import statement outside a module"
# Make sure package.json has "type": "module" npm pkg set type=module
"Module not found" errors
# Reinstall dependencies rm -rf node_modules package-lock.json npm install
TypeScript compilation errors
# Check tsconfig.json configuration # Make sure all dependencies are installed npm install --save-dev @types/node
Server connection issues
# Check if server is running ps aux | grep tsx # Check for port conflicts lsof -i :3000 # if using HTTP wrapper

Debug Mode

Enable debug logging:

DEBUG=true npx tsx satim-mcp-server.ts

Integration Requirements

SSL Security

Mandatory: Your website must have SSL certificate
All API calls must use HTTPS

User Interface Requirements

Payment Page

Display final amount prominently (bold, larger font)
Include CAPTCHA to prevent automated submissions
Show CIB logo on payment button
Display terms and conditions with customer acknowledgment
Redirect to SATIM page in independent browser window

Success Page Display

For accepted payments, show:

Transaction message (respCode_desc)
Transaction ID (orderId)
Order number (orderNumber)
Authorization code (approvalCode)
Transaction date/time
Payment amount with currency
Payment method (CIB/Edhahabia)
SATIM contact: 3020 3020

Success Page Actions

Print receipt option
Download PDF receipt
Email PDF receipt to third party

Rejection Page

Display rejection message in three languages
Show SATIM contact information

Amount Handling

Amounts must be multiplied by 100 when sent to SATIM:

50.00 DA → send 5000
806.50 DA → send 80650

The MCP server handles this conversion automatically.

Error Handling

Order Registration Errors

Invalid credentials
Duplicate order number
Invalid amount (< 50 DA)
Missing required parameters

Confirmation Errors

Error Code	Description
0	Successfully confirmed
1	Empty order ID
2	Already confirmed
3	Access denied
5	Access denied
6	Unknown order
7	System error

Refund Errors

Error Code	Description
0	No system error
5	Password change required / Empty order ID
6	Wrong order number
7	Payment state error / Amount error / System error

Examples

Complete Payment Flow

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

Processing Refunds

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

Security Considerations

Credentials Management

Store credentials securely (environment variables, key vault)
Use HTTPS for all communications
Implement proper authentication for your API endpoints

Order Number Security

Use unique, non-sequential order numbers
Include timestamp or random elements
Validate order ownership before confirmation

Data Validation

Always validate amounts on server side
Verify order status before processing confirmations
Implement idempotency for refund operations

Logging and Monitoring

Log all payment transactions
Monitor for suspicious activities
Implement rate limiting for API calls

Production Deployment

Environment Configuration

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

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

Health Checks

Implement health check endpoints to monitor gateway connectivity:

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

Support and Contact

SATIM Support: 3020 3020 (toll-free)
Technical Issues: Contact your integration specialist
Documentation: Refer to official SATIM integration guides

This MCP server implementation follows SATIM's official API specifications and includes all required integration points for Algerian e-commerce platforms.

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

A Model Context Protocol (MCP) server for integrating with the SATIM payment gateway system in Algeria, enabling AI assistants to process CIB/Edhahabia card payments through the SATIM-ePAY platform.

Related Resources

Reddit Discussion about this server

Related MCP Servers

PayPal MCP Server
arbuthnot-eth
-
security
A
license
-
quality
A Model Context Protocol server that provides comprehensive integration with PayPal's APIs, enabling seamless interaction with payment processing, invoicing, subscription management, and business operations through a standardized interface.
Last updated -
TypeScript
Apache 2.0
claude-mcp-server
paybyrd
-
security
F
license
-
quality
A Model Context Protocol server that enables Claude AI to interact with Paybyrd's payment processing API, allowing for creating payment links, processing refunds, and retrieving order information.
Last updated -
5
TypeScript
Aligo SMS MCP Server
hongsw
-
security
A
license
-
quality
A Model Context Protocol (MCP) server that allows AI agents like Claude to interact with the Aligo SMS API to send text messages and retrieve related information.
Last updated -
JavaScript
MIT License
Daraja MCP
jameskanyiri
-
security
F
license
-
quality
A Model Context Protocol server that integrates AI applications with Safaricom's Daraja API, enabling AI-driven financial transactions and automation through M-Pesa services.
Last updated -
2
Python

View all related MCP servers