Satim Payment Gateway Integration

Instructions

Implementation Reference

• satim-mcp-server.ts:371-406 (handler)

  MCP CallToolRequest handler for the 'register_order' tool: checks if credentials are configured, prepares jsonParams and OrderRegistrationParams from input arguments, invokes SatimPaymentGateway.registerOrder, and returns the response as text content.
  case "register_order": if (!satimGateway) { throw new McpError(ErrorCode.InvalidRequest, "Credentials not configured. Use configure_credentials first."); } const jsonParams: any = { force_terminal_id: args.force_terminal_id as string, udf1: args.udf1 as string, }; // Add optional parameters only if they exist if (args.udf2) jsonParams.udf2 = args.udf2 as string; if (args.udf3) jsonParams.udf3 = args.udf3 as string; if (args.udf4) jsonParams.udf4 = args.udf4 as string; if (args.udf5) jsonParams.udf5 = args.udf5 as string; const registrationResponse = await satimGateway.registerOrder({ orderNumber: args.orderNumber as string, amount: SatimPaymentGateway.convertAmountToCentimes(args.amountInDA as number), currency: (args.currency as string) || "012", returnUrl: args.returnUrl as string, failUrl: args.failUrl as string, description: args.description as string, language: args.language as 'AR' | 'FR' | 'EN', jsonParams }); return { content: [ { type: "text", text: JSON.stringify(registrationResponse, null, 2) } ] };
• satim-mcp-server.ts:98-118 (handler)

  Core handler logic in SatimPaymentGateway class: authenticates with SATIM credentials, builds query parameters from OrderRegistrationParams, performs HTTP GET to /register.do endpoint, returns the API response.
  async registerOrder(params: OrderRegistrationParams): Promise<OrderRegistrationResponse> { try { const queryParams = new URLSearchParams({ userName: this.credentials.userName, password: this.credentials.password, orderNumber: params.orderNumber, amount: params.amount.toString(), currency: params.currency, returnUrl: params.returnUrl, ...(params.failUrl && { failUrl: params.failUrl }), ...(params.description && { description: params.description }), ...(params.language && { language: params.language }), jsonParams: JSON.stringify(params.jsonParams) }); const response = await axios.get(`${this.baseUrl}/register.do?${queryParams}`); return response.data; } catch (error) { throw new Error(`Order registration failed: ${error}`); } }
• satim-mcp-server.ts:19-35 (schema)

  TypeScript interface defining the internal parameters structure for order registration used by SatimPaymentGateway.registerOrder.
  interface OrderRegistrationParams { orderNumber: string; amount: number; // Amount in centimes (multiply by 100) currency: string; // ISO 4217 (012 for DZD) returnUrl: string; failUrl?: string; description?: string; language?: 'AR' | 'FR' | 'EN'; jsonParams: { force_terminal_id: string; // Mandatory udf1: string; // Mandatory udf2?: string; udf3?: string; udf4?: string; udf5?: string; }; }
• satim-mcp-server.ts:230-282 (registration)

  MCP tool registration descriptor returned by ListToolsRequestHandler, specifying name, description, and detailed inputSchema with properties and required fields.
  { name: "register_order", description: "Register a new order with SATIM payment gateway", inputSchema: { type: "object", properties: { orderNumber: { type: "string", description: "Unique order identifier in merchant's system" }, amountInDA: { type: "number", description: "Order amount in Algerian Dinars (minimum 50 DA)" }, currency: { type: "string", description: "Currency code according to ISO 4217 (012 for DZD)", default: "012" }, returnUrl: { type: "string", description: "URL to redirect after successful payment" }, failUrl: { type: "string", description: "URL to redirect after failed payment" }, description: { type: "string", description: "Order description" }, language: { type: "string", enum: ["AR", "FR", "EN"], description: "Language for the payment interface" }, force_terminal_id: { type: "string", description: "Terminal ID assigned by bank (mandatory)" }, udf1: { type: "string", description: "SATIM specific parameter (mandatory)" }, udf2: { type: "string", description: "Additional parameter" }, udf3: { type: "string", description: "Additional parameter" }, udf4: { type: "string", description: "Additional parameter" }, udf5: { type: "string", description: "Additional parameter" } }, required: ["orderNumber", "amountInDA", "returnUrl", "force_terminal_id", "udf1"] } }, {
• satim-mcp-server.ts:163-165 (helper)

  Static helper method used in register_order to convert amount from DA to centimes before API call.
  static convertAmountToCentimes(amountInDA: number): number { return Math.round(amountInDA * 100); }