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