Satim Payment Gateway Integration

Instructions

Implementation Reference

• satim-mcp-server.ts:426-446 (handler)

  MCP server handler for the 'refund_order' tool: validates gateway configuration, converts input amount to centimes, invokes SatimPaymentGateway.refundOrder, and serializes the response as JSON text content.

  case "refund_order":
    if (!satimGateway) {
      throw new McpError(ErrorCode.InvalidRequest, "Credentials not configured. Use configure_credentials first.");
    }
  
    const refundResponse = await satimGateway.refundOrder({
      orderId: args.orderId as string,
      amount: SatimPaymentGateway.convertAmountToCentimes(args.amountInDA as number),
      currency: args.currency as string,
      language: args.language as 'AR' | 'FR' | 'EN'
    });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(refundResponse, null, 2)
        }
      ]
    };

• satim-mcp-server.ts:301-328 (registration)

  Registration of the 'refund_order' tool in the MCP listTools response, defining its name, description, and JSON input schema.

  {
    name: "refund_order",
    description: "Process refund for a completed order",
    inputSchema: {
      type: "object",
      properties: {
        orderId: {
          type: "string",
          description: "Order ID to refund"
        },
        amountInDA: {
          type: "number",
          description: "Refund amount in Algerian Dinars"
        },
        currency: {
          type: "string",
          description: "Currency code",
          default: "012"
        },
        language: {
          type: "string",
          enum: ["AR", "FR", "EN"],
          description: "Language for response messages"
        }
      },
      required: ["orderId", "amountInDA"]
    }
  },

• satim-mcp-server.ts:142-158 (helper)

  Core refundOrder method in SatimPaymentGateway class: builds authenticated query parameters and performs HTTP GET to SATIM's refund.do endpoint.

  async refundOrder(params: RefundParams): Promise<RefundResponse> {
    try {
      const queryParams = new URLSearchParams({
        userName: this.credentials.userName,
        password: this.credentials.password,
        orderId: params.orderId,
        amount: params.amount.toString(),
        ...(params.currency && { currency: params.currency }),
        ...(params.language && { language: params.language })
      });
  
      const response = await axios.get(`${this.baseUrl}/refund.do?${queryParams}`);
      return response.data;
    } catch (error) {
      throw new Error(`Refund failed: ${error}`);
    }
  }

• satim-mcp-server.ts:75-86 (schema)

  TypeScript interfaces defining input (RefundParams) and output (RefundResponse) structures for the refund operation.

  interface RefundParams {
    orderId: string;
    amount: number; // Amount in centimes
    currency?: string;
    language?: 'AR' | 'FR' | 'EN';
  }
  
  interface RefundResponse {
    errorCode: number;
    errorMessage?: string;
  }