Satim Payment Gateway Integration

Integrate with Algeria's SATIM payment gateway to process CIB and Edhahabia card payments.

Obviously you should have already an account created and working to get credentials from here :https://cibweb.dz/fr/login

# 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

- Installation
- Configuration
- Payment Flow
- Tools
- Testing
- Integration Requirements
- Error Handling
- Examples
- Security Considerations

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

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

# Compile TypeScript npm run build # Run compiled JavaScript npm start

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

Before using any payment tools, configure your SATIM credentials:

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

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

The complete payment process follows these steps:

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

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

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

Based on validation results, display appropriate messages to customers.

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

- 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

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

Confirm order status after payment attempt.

- orderId(string, required): Order ID from registration
- language(string, optional): Response 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(string, required): Order ID to refund
- amountInDA(number, required): Refund amount in DA
- currency(string, optional): Currency code
- language(string, optional): Response language

Validate and interpret payment response.

- response(object, required): Order confirmation response

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

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

Createtest-client.tsfollowing the example in the documentation, then run:

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

"Cannot use import statement outside a module"

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

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

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

# Check if server is running ps aux | grep tsx # Check for port conflicts lsof -i :3000 # if using HTTP wrapper

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

- 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

- 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

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

- Display rejection message in three languages
- Show SATIM contact information

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.

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

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

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

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

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

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

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

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

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

The PayPal Model Context Protocol server allows you to integrate with PayPal APIs through function calling. This protocol supports various tools to interact with different PayPal services.

Interact with the Gumroad API to access and manage your products, sales, and creator data.

An MCP server for processing payments using stdio transport, configured via environment variables.

Interact with the Paddle Billing API to manage products, prices, customers, transactions, and subscriptions.

Access the Yuno payment platform API to manage payments, customers, and checkouts programmatically.

Transaction-complete hotel booking over MCP — 300K+ properties, real hotel confirmation numbers, loyalty points, secure checkout. Hotels are merchant of record. Builders set their own booking fee via Stripe Connect. Built on proven distribution infrastructure.

Mercado Pago's official MCP server, offering tools to interact with our API, simplifying tasks and product integration.

A Model Context Protocol (MCP) server for square

Static MCP discovery card for x402 spend-policy, paid MCP launch guidance, seller checkout repair, and agent-payment safety APIs.

Integrate AI tools and agents with Cashfree's Payment Gateway, Payouts, and SecureID APIs.